Admin Endpoints Reference¶

This page documents the admin API surface — endpoints that require elevated permissions (tenant:manage, graph:rebuild, audit:read, super_admin). These endpoints are not visible in the patient-facing Swagger UI.

All admin endpoints are under /api/v1/admin/ and require a valid Clerk JWT with the appropriate Clerk organisation role mapped to an internal permission. See Auth & Privacy for the RBAC mapping.

Graph Management¶

Rebuild Neo4j projection¶

POST /api/v1/admin/graph/rebuild
Permission: graph:rebuild

Triggers a full or scoped re-projection of PostgreSQL data into Neo4j. Use after bulk imports, schema migrations, or when node counts diverge.

Request body:

{
  "scope": "all"
}

scope options: "all" | "providers" | "doctors" | "procedures"

Response:

{
  "success": true,
  "data": {
    "counts": {
      "doctors": 172,
      "providers": 42,
      "procedures": 30
    },
    "duration_ms": 4210
  }
}

Source: app/routers/admin_graph.py. See Graph Projection architecture for the projection contract.

Feature Flags¶

Get effective flags for a tenant¶

GET /api/v1/admin/flags/effective?tenant_id={tenant_id}
Permission: tenant:manage

Returns the resolved flag values for a tenant, merging Flagsmith environment defaults with any per-identity overrides. Useful for debugging flag state without accessing Flagsmith cloud.

Response:

{
  "success": true,
  "data": {
    "flags": {
      "matching_strategy_version": "v2.1",
      "enable_mso_booking": true,
      "triage_risk_threshold": 0.65
    },
    "overrides_applied": ["triage_risk_threshold"]
  }
}

Set a per-tenant flag override¶

POST /api/v1/admin/flags/identity-override
Permission: tenant:manage

Sets a Flagsmith per-identity override for a tenant. This is the only supported path for per-tenant overrides — never use the Flagsmith dashboard UI for tenant-specific values (see feedback_flagsmith_identity_overrides.md).

Request body:

{
  "tenant_id": "t_01abc...",
  "flag_key": "triage_risk_threshold",
  "value": 0.70
}

Every override is audit-logged as EventType.ADMIN_FLAG_IDENTITY_OVERRIDE.

Source: app/routers/admin_flags.py.

Matching Dashboard¶

Get parameter registry status¶

GET /api/v1/admin/matching/parameters
Permission: tenant:manage

Returns all 147 matching parameters from the registry (config/matching/parameters/*.yaml) with their current status, coverage, and source.

Response:

{
  "success": true,
  "data": {
    "parameters": [
      {
        "id": "jci_accreditation",
        "domain": "provider_capability",
        "status": "active",
        "source": "postgres",
        "coverage_pct": 0.82,
        "last_refresh": "2026-05-07T08:00:00Z"
      }
    ],
    "total": 147,
    "active": 14,
    "seeded": 12,
    "unseeded": 89,
    "not_implemented": 32
  }
}

Get domain weight configuration¶

GET /api/v1/admin/matching/weights
Permission: tenant:manage

Returns current domain-level weight configuration — either from Flagsmith override (per tenant) or the YAML default.

Source: app/routers/admin_matching.py. See ADR-0026 for the parameter registry design.

MSO Session Management¶

List MSO sessions¶

GET /api/v1/admin/mso/sessions
Permission: tenant:manage

Query parameters:

Refund a session¶

POST /api/v1/admin/mso/sessions/{session_id}/refund
Permission: tenant:manage

Triggers a refund via the original payment provider (Stripe or Razorpay) and sets MSOSession.status = refunded. Idempotent — calling twice does not double-refund.

Source: app/routers/admin_mso_sessions.py.

MSO Doctor Management¶

List MSO doctors¶

GET /api/v1/admin/mso-doctors
Permission: tenant:manage

Query parameters: specialty, language, available_from, tenant_id.

Onboard MSO doctor¶

POST /api/v1/admin/mso-doctors
Permission: tenant:manage

Update MSO doctor¶

PATCH /api/v1/admin/mso-doctors/{doctor_id}
Permission: tenant:manage

Source: app/routers/admin_mso_doctors.py.

Triage Management¶

The triage admin UI is at /admin/triage. Thresholds are set via Flagsmith per-identity overrides — see Triage Tuning Runbook for the step-by-step procedure.

Audit Log¶

Query audit log¶

GET /api/v1/admin/audit-log
Permission: audit:read

Queries the append-only audit_logs table. Supports filtering by action, actor_id, tenant_id, case_id, patient_id, and date range.

Source: app/routers/admin_audit_log.py.

Tenant Management¶

Create provider tenant¶

POST /api/v1/admin/providers/{provider_id}/tenant
Permission: tenant:manage

Legacy 2-step path: creates a tenant for an existing provider. For new providers, prefer the unified POST /api/v1/admin/providers endpoint which creates provider + tenant atomically.

List tenants¶

GET /api/v1/admin/tenants
Permission: super_admin

Update tenant settings¶

PATCH /api/v1/admin/tenants/{tenant_id}/settings
Permission: tenant:manage

Source: app/routers/admin_portal.py, app/routers/admin_tenants.py.

User & Role Management¶

List users for a tenant¶

GET /api/v1/admin/users?tenant_id={tenant_id}
Permission: tenant:manage

Assign role to user¶

POST /api/v1/admin/users/{user_id}/roles
Permission: tenant:manage

Assigns a Clerk org role (mapped to internal permission set) to a user. The Clerk user ID is verified against the Clerk API before the role is applied. See feedback_verify_user_id_against_clerk.md.

Source: app/routers/admin_users.py, app/routers/admin_roles.py.

System Health¶

External dependency health¶

GET /api/v1/admin/health/external-deps
Permission: super_admin

Returns health status of all external services: Daily.co, Stripe, Razorpay, Neo4j, Qdrant, Redis, Anthropic, Langfuse.

Error Codes¶

Admin endpoints use the standard AUTH_*, TENANT_*, and GRAPH_* error code namespaces. See Error Codes for the full list.

Common admin errors: