Operations And Observability

Health, deployment-auth, system-health, queue status, and internal issue intake APIs.

Owner: Platform operations backend

Source Modules

• scripts/serve_client_portal.py
• LeafEnterprise/system_health.py
• LeafEnterprise/issue_inbox.py

Endpoint Summary

Method	Path	Summary	Auth	Handler
GET	/api/deployment-auth	Reports trusted proxy and proxied identity posture for hosted rollout validation.	trusted frontend proxy	_handle_deployment_auth
GET	/api/health	Public uptime check for the backend process.	public	inline health handler
GET	/api/ops/issues	Lists internal issue inbox records.	trusted frontend proxy	_handle_issue_inbox_list
POST	/api/ops/issues	Submits an internal bug, data, access, or performance issue.	trusted frontend proxy	_handle_issue_inbox_submit
GET	/api/queue/status	Returns run queue state for local/internal operations.	trusted frontend proxy	_handle_queue_status
GET	/api/system-health	Protected internal runtime health and observability snapshot.	trusted frontend proxy	_handle_system_health

Endpoint Details

GET /api/deployment-auth

Reports trusted proxy and proxied identity posture for hosted rollout validation.

Property	Value
Handler	_handle_deployment_auth
Auth	trusted frontend proxy
Cache	none
Status codes	200, 401

Query parameters: none

Body fields: none

Response sections: status, auth_source, proxied_identity, deployment_mode

Tests / smoke paths: tests/test_deployment_auth.py, scripts/smoke_deployment_site.py

Notes: Use this to confirm Cloudflare Access identity reached the backend through the frontend proxy.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/deployment-auth
• Route family: ops-observability
• Source handler: _handle_deployment_auth
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

GET /api/health

Public uptime check for the backend process.

Property	Value
Handler	inline health handler
Auth	public
Cache	none
Status codes	200

Query parameters: none

Body fields: none

Response sections: status, service, generated_at_utc

Tests / smoke paths: tests/test_deployment_auth.py, scripts/smoke_client_portal.py

Notes: Keep this as the narrow public exception; all other internal API routes should remain protected.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/health
• Route family: ops-observability
• Source handler: inline health handler
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

GET /api/ops/issues

Lists internal issue inbox records.

Property	Value
Handler	_handle_issue_inbox_list
Auth	trusted frontend proxy
Cache	none
Status codes	200, 401, 500

Query parameters: status, limit

Body fields: none

Response sections: issues, summary, pagination

Tests / smoke paths: scripts/smoke_client_portal.py

Notes: Uses Leaf-owned SQLite issue records with proxied identity context.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/ops/issues
• Route family: ops-observability
• Source handler: _handle_issue_inbox_list
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

POST /api/ops/issues

Submits an internal bug, data, access, or performance issue.

Property	Value
Handler	_handle_issue_inbox_submit
Auth	trusted frontend proxy
Cache	none
Status codes	200, 201, 400, 401, 500

Query parameters: none

Body fields: title, issue_type, severity, route, description, repro_steps, metadata

Response sections: issue, status

Tests / smoke paths: scripts/smoke_client_portal.py

Notes: Captures employee identity from protected headers when available.

Semantic Retrieval Hints

• Stable endpoint id: POST /api/ops/issues
• Route family: ops-observability
• Source handler: _handle_issue_inbox_submit
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

GET /api/queue/status

Returns run queue state for local/internal operations.

Property	Value
Handler	_handle_queue_status
Auth	trusted frontend proxy
Cache	none
Status codes	200, 401, 500

Query parameters: none

Body fields: none

Response sections: status, queued, running, completed, failed

Tests / smoke paths: scripts/smoke_client_portal.py

Notes: Queue status should reflect the backend queue model, not inferred browser state.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/queue/status
• Route family: ops-observability
• Source handler: _handle_queue_status
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.

GET /api/system-health

Protected internal runtime health and observability snapshot.

Property	Value
Handler	_handle_system_health
Auth	trusted frontend proxy
Cache	none
Status codes	200, 401, 500

Query parameters: none

Body fields: none

Response sections: status, runtime, request_windows, queue, cache, deployment

Tests / smoke paths: scripts/smoke_client_portal.py, scripts/smoke_deployment_site.py

Notes: App-native health surface; not a replacement for vendor dashboards or full tracing.

Semantic Retrieval Hints

• Stable endpoint id: GET /api/system-health
• Route family: ops-observability
• Source handler: _handle_system_health
• Secrets and raw source URLs must remain backend-only unless this endpoint explicitly documents otherwise.