Gateway API — REST Reference¶

The Opencomplai gateway API is the HTTP entry point for the Docker Compose stack. All endpoints are prefixed /v1/ except GET /health.

Base URL (default): http://localhost:8080 Content-Type: application/json for all request and response bodies. Authentication: every endpoint except GET /health needs credentials; see Authentication.

A manifest can name several frameworks to assess side by side (compliance_targets). Risk classification (/v1/risk/classify), dossier generation (/v1/docs/generate) and the risk engine's public /v1/checker/* routes are EU AI Act only.

Authentication¶

Every endpoint except GET /health requires credentials. The gateway is fail-closed: it refuses to start unless authentication is configured, or explicitly switched off for local development with OPENCOMPLAI_AUTH_DISABLED=1. A deployment uses one of two modes; see Authentication to set them up.

When OIDC_JWKS_URI is set the gateway uses OIDC mode and ignores OPENCOMPLAI_API_KEY.

curl -s http://localhost:8080/v1/portfolio -H "x-api-key: $OPENCOMPLAI_API_KEY"

Authentication and rate limiting add these responses to every /v1 endpoint:

The first two use the gateway error envelope below. The last is the rate limiter's own body, with a Retry-After header in seconds:

{
  "statusCode": 429,
  "error": "Too Many Requests",
  "message": "Rate limit exceeded, retry in 1 minute"
}

Error responses¶

Errors come in three shapes, depending on who produced them.

Gateway envelope. The gateway itself answers with this body when authentication fails, when it rejects a request body, and when it cannot reach an internal service:

{
  "error_code": "DEPENDENCY_UNAVAILABLE",
  "message": "Upstream service unavailable: http://risk-engine:8001/v1/risk/classify",
  "category": "dependency",
  "retryable": true,
  "correlation_id": "req-1"
}

Forwarded service errors. When an internal service answers with an error, the gateway returns that response unchanged, status code included. The services are FastAPI apps, so the body is {"detail": ...} where detail is a string, an object (for example {"error_code": "IDEMPOTENCY_CONFLICT", "message": "...", "category": "client", "retryable": false}) or, for request validation failures, a list of error objects. A 404, 409, 422 or 502 on a proxied endpoint therefore usually has this shape rather than the envelope. Each endpoint below says which one it returns.

Egress proxy errors. The egress proxy's refusals are not wrapped in detail: POST /v1/sync/metadata returns EGRESS_BLOCKED (403) as {"error_code", "message", "category": "policy", "retryable", "policy_hash"}.

GET /health¶

Health check for the gateway API process. The only endpoint that needs no credentials.

Request: No body.

Response 200:

{
  "status": "ok",
  "service": "gateway-api",
  "version": "0.9.1"
}

POST /v1/manifests/validate¶

Validate a system manifest against the SystemManifest schema and forward to the risk engine for further validation.

Request body:

{
  "system_id": "loan-decision-model",
  "intended_purpose": "automated credit scoring for retail lending",
  "compliance_targets": ["EU_AI_ACT", "NIST_AI_RMF"],
  "framework_inputs": {
    "NIST_AI_RMF": {
      "excluded": {"NIST_AI_RMF:MAP 1.1": "Internal tool, no external users"}
    }
  },
  "high_risk_presumption": false,
  "commit_ref": "abc1234"
}

Response 200:

{
  "valid": true,
  "manifest": {
    "system_id": "loan-decision-model",
    "intended_purpose": "automated credit scoring for retail lending",
    "compliance_targets": ["EU_AI_ACT", "NIST_AI_RMF"],
    "high_risk_presumption": false,
    "commit_ref": "abc1234"
  }
}

manifest is the validated manifest with defaults applied; the example is shortened.

Response 422: VALIDATION_ERROR in the gateway envelope when the gateway rejects the body: a required field missing or empty, a wrong type, or an empty compliance_targets list. An unknown framework id is rejected by the risk engine instead and comes back as {"detail": "<message>"}.

POST /v1/risk/classify¶

EU AI Act only. Classify the risk level of an AI system under EU AI Act Annex III.

Request body:

{
  "system_id": "loan-decision-model",
  "intended_purpose": "automated credit scoring for retail lending"
}

Response 200:

{
  "risk_class": "high",
  "trap_detected": false,
  "profiling_detected": false,
  "rationale_hash": "sha256:3e2f1a...",
  "evidence_event_id": "evt_sha256:9c1d4f..."
}

POST /v1/verify/claims¶

Submit a ground-truth verification task (REQ-GTVG-001).

Request body:

{
  "system_id": "loan-decision-model",
  "claim_ref": "accuracy-claim-2026-05",
  "source_ref": "https://internal-benchmarks/accuracy",
  "expected_value": "0.94"
}

Response 200:

{
  "task_id": "b7f3a1e2-...",
  "claim_ref": "accuracy-claim-2026-05",
  "source_ref": "https://internal-benchmarks/accuracy",
  "outcome": "pending"
}

outcome is pending until the verification task worker completes. Poll or wait for the compliance_check_completed event.

POST /v1/hitl/overrides¶

Submit a human-in-the-loop override with a mandatory rationale (REQ-HITL-001). The decision is written to the evidence ledger before it is accepted; if the ledger is unavailable the request fails with 503 AUDIT_UNAVAILABLE and nothing is recorded.

Request body:

{
  "case_id": "case-2026-0142",
  "actor_id": "j.doe@example.com",
  "rationale": "Applicant income verified manually against payslips.",
  "decision": "approved"
}

Response 201:

{
  "override_id": "ovr_sha256:7a0c19...",
  "rationale_hash": "sha256:3e2f1a...",
  "status": "accepted",
  "vault_event_id": "e1a2b3c4-..."
}

Response 422: VALIDATION_ERROR — case_id, actor_id or rationale is missing or empty, or decision is not approved or rejected. A whitespace-only rationale is rejected by the risk engine and comes back as {"detail": {...}} instead of the envelope.

Response 409: IDEMPOTENCY_CONFLICT — idempotency_key was already used with a different payload. Returned as {"detail": {...}}.

POST /v1/hitl/overrides/{override_id}/second-approval¶

Complete a dual-control override that was started with requires_dual_approval. A second approver, distinct from the first, confirms or rejects it. The override_second_approved event is written to the evidence ledger before the request is accepted; if the ledger is unavailable the request fails with 503 AUDIT_UNAVAILABLE and the override stays pending, so the call can be retried. In API-key mode every caller is the same principal (api-key-caller), so two distinct approvers need JWT/OIDC authentication.

Request body:

{
  "actor_id": "m.roe@example.com",
  "rationale": "Reviewed the payslips and agree with the first approver.",
  "rationale_hash": "sha256:3e2f1a...",
  "decision": "approved"
}

Response 201:

{
  "override_id": "ovr_sha256:7a0c19...",
  "rationale_hash": "sha256:9d4b02...",
  "status": "accepted",
  "vault_event_id": "e1a2b3c4-..."
}

status is accepted or, when the second approver rejects, rejected; rationale_hash is the hash of the second rationale.

Response 403: POLICY_DENIED — the second approver is the same actor as the first. Response 404: no pending override with this id. Response 409: ALREADY_COMPLETED or RATIONALE_HASH_MISMATCH. Response 422: VALIDATION_ERROR. Response 503: AUDIT_UNAVAILABLE.

GET /v1/hitl/queue¶

List items in the human-review queue.

Query parameters:

Response 200:

{
  "items": [
    {
      "review_id": "rev_sha256:5b1c8e...",
      "tenant_id": "default",
      "system_id": "loan-decision-model",
      "commit_ref": "abc1234",
      "reason": "evaluator_fail",
      "state": "assigned",
      "payload_ref": "sha256:9c1d4f...",
      "context_ref": "sha256:3e2f1a...",
      "reviewer_group": "compliance-reviewers",
      "assigned_to": "compliance-reviewers:member-0",
      "idempotency_key": "rev_sha256:5b1c8e...",
      "created_at": "2026-05-25T10:00:00+00:00",
      "expires_at": "2026-05-28T10:00:00+00:00",
      "decided_at": null,
      "linked_override_id": null
    }
  ]
}

The remaining fields (tenant_id, system_id, commit_ref, idempotency_key, created_at) identify the item and when it was created.

GET /v1/hitl/queue/{id}¶

Get one review item together with its redacted reviewer context. The context never carries raw prompts, outputs or personal data.

Response 200:

{
  "item": {
    "review_id": "rev_sha256:5b1c8e...",
    "tenant_id": "default",
    "system_id": "loan-decision-model",
    "commit_ref": "abc1234",
    "reason": "evaluator_fail",
    "state": "assigned",
    "payload_ref": "sha256:9c1d4f...",
    "context_ref": "sha256:3e2f1a...",
    "reviewer_group": "compliance-reviewers",
    "assigned_to": "compliance-reviewers:member-0",
    "idempotency_key": "rev_sha256:5b1c8e...",
    "created_at": "2026-05-25T10:00:00+00:00",
    "expires_at": "2026-05-28T10:00:00+00:00",
    "decided_at": null,
    "linked_override_id": null
  },
  "context": {
    "review_id": "pending",
    "reason": "evaluator_fail",
    "detector_ids": ["..."],
    "masked_excerpts": [],
    "aggregate_counts": {"failed": 1},
    "evidence_hashes": ["sha256:9c1d4f..."]
  }
}

context is null when no context is stored for the item.

Response 404: the review item does not exist. Returned as {"detail": "Review item not found"}.

POST /v1/hitl/queue/{id}/assign¶

Assign a review item to a reviewer.

Request body:

{
  "reviewer_id": "j.doe@example.com"
}

Response 200: {"item": {...}} — the updated review item, now assigned to the reviewer.

Response 404: the review item does not exist. Response 422: VALIDATION_ERROR — reviewer_id missing or empty.

POST /v1/hitl/queue/{id}/decide¶

Record the decision on a review item. This submits a HITL override with the review id as the case (same rules as POST /v1/hitl/overrides) and marks the item decided.

Request body:

{
  "actor_id": "j.doe@example.com",
  "decision": "rejected",
  "rationale": "Evaluator failure confirmed on manual re-run."
}

Response 201: {"item": {...}, "override": {...}} — the updated review item (decided, with linked_override_id set) and the override as returned by POST /v1/hitl/overrides.

Response 404: the review item does not exist. Response 409: IDEMPOTENCY_CONFLICT. Response 422: VALIDATION_ERROR. Response 503: AUDIT_UNAVAILABLE — the ledger write failed and the decision was not recorded.

POST /v1/docs/generate¶

EU AI Act only. Generate an EU AI Act Annex IV technical documentation dossier (REQ-DOC-001). The gateway forwards the body unchanged to the doc generator, which validates it. The dossier is stored in the evidence vault and can be fetched later with GET /v1/docs/{dossier_id}.

Request body:

{
  "system_id": "loan-decision-model",
  "commit_ref": "abc1234",
  "intended_purpose": "automated credit scoring for retail lending",
  "provider_name": "ACME Financial AI"
}

The request also accepts the optional Annex IV inputs training_data_description, model_architecture, performance_metrics (an object of numbers), known_limitations, human_oversight_measures, monitoring_approach, incident_response_procedure, metrics_appropriateness_rationale, lifecycle_changes, change_log_reference, harmonised_standards, alternative_solutions, eu_declaration_of_conformity_ref, post_market_monitoring_plan_ref and post_market_monitoring_summary, which are recorded in the dossier as given, and the full eval_report and corroboration_report objects, which are validated before use.

Response 200:

{
  "dossier_id": "d4f9c2a1-...",
  "bundle_checksum": "sha256:3e2f1a...",
  "status": "generated",
  "duration_ms": 142,
  "signature": null,
  "schema_valid": true,
  "content_hash": "sha256:7d2e90...",
  "ledger_event_id": "e1a2b3c4-..."
}

Response 422: returned as {"detail": ...}. By default a dossier that fails the Annex IV schema check is refused with DOSSIER_SCHEMA_INVALID. It is still stored, and detail carries dossier_id, bundle_checksum, content_hash, ledger_event_id and schema_valid: false, so you can retrieve what failed with GET /v1/docs/{dossier_id}; set allow_incomplete to receive 200 instead. INVALID_EVAL_REPORT and INVALID_CORROBORATION_REPORT mean the matching report object did not validate, and a missing system_id or commit_ref returns a list of validation errors.

Response 500: SYSTEM_ERROR — generation failed unexpectedly. Response 502: the dossier was generated but could not be stored in the evidence vault.

GET /v1/docs¶

EU AI Act only. List the dossiers generated for a system, newest first.

Query parameters:

Response 200:

{
  "system_id": "loan-decision-model",
  "count": 1,
  "dossiers": [
    {
      "dossier_id": "d4f9c2a1-...",
      "system_id": "loan-decision-model",
      "commit_ref": "abc1234",
      "content_hash": "sha256:7d2e90...",
      "bundle_checksum": "sha256:3e2f1a...",
      "ledger_event_id": "e1a2b3c4-...",
      "created_at": "2026-05-25T10:00:00+00:00"
    }
  ]
}

Response 422: VALIDATION_ERROR — system_id is missing.

GET /v1/docs/{dossier_id}¶

EU AI Act only. Retrieve a previously generated dossier by the dossier_id that POST /v1/docs/generate returned.

Response 200: the index fields shown for GET /v1/docs plus the stored dossier:

{
  "dossier_id": "d4f9c2a1-...",
  "system_id": "loan-decision-model",
  "commit_ref": "abc1234",
  "bundle_checksum": "sha256:3e2f1a...",
  "content_hash": "sha256:7d2e90...",
  "ledger_event_id": "e1a2b3c4-...",
  "created_at": "2026-05-25T10:00:00+00:00",
  "dossier": {}
}

dossier is the Annex IV dossier JSON as it was generated. bundle_checksum and ledger_event_id let you verify it and trace the ledger event that anchors it.

Response 404: no such dossier for the caller's tenant. Returned as {"detail": "Dossier not found: <dossier_id>"}. Response 502: the dossier index or its stored content could not be read.

POST /v1/evidence/events¶

Append an event to the append-only Merkle-linked evidence ledger.

Request body:

{
  "event_type": "compliance_check_started",
  "payload": {
    "install_id": "a1b2c3d4-...",
    "system_id": "loan-decision-model",
    "commit_ref": "abc1234",
    "scan_mode": "ci"
  },
  "signer_id": null
}

Response 201:

{
  "event_id": "e1a2b3c4-...",
  "payload_hash": "sha256:9c1d4f...",
  "prev_hash": "sha256:41ab07..."
}

prev_hash is the chain tip the new event links to.

GET /v1/evidence/verify-chain¶

Verify the integrity of the caller's evidence ledger. Each tenant has its own independent chain.

Response 200:

{
  "valid": true
}

valid is true when every event still links to its predecessor.

GET /v1/evidence/ledger-root¶

Return the current Merkle tip of the ledger: the hash an Annex IV dossier anchors to, so later tampering with older events can be detected.

Response 200:

{
  "ledger_root_hash": "sha256:9c1d4f..."
}

For an empty ledger this is the genesis hash, the SHA-256 of the empty string.

GET /v1/evidence/ledger-history-tips¶

Return the rolling Merkle tip after every event, so you can confirm that a dossier's recorded ledger_root_hash is a real point in the chain. Read the chain a page at a time with limit and after_seq; without them the whole list comes back in one response, which is only allowed for ledgers of up to 10,000 events.

Query parameters:

Response 200, without limit:

{
  "tips": ["sha256:e3b0c4...", "sha256:9c1d4f..."],
  "count": 2
}

tips lists the genesis hash first, then the tip after each event in append order.

Response 200, with limit:

{
  "genesis": "sha256:e3b0c4...",
  "tips": ["sha256:9c1d4f...", "sha256:41ab07..."],
  "count": 2,
  "next_after_seq": 2
}

genesis is the hash of an empty ledger and is not part of tips, which holds only the per-event tips of this page. Pass next_after_seq back as after_seq to fetch the next page; it is null on the last page. Each page is read from the database with a bounded query, so memory use does not grow with the ledger.

Response 413: the ledger has more than 10,000 events and the request did not use limit. Page through it with limit and after_seq.

Response 422: after_seq was given without limit, or a parameter is out of range.

POST /v1/sync/metadata¶

Sync allowlisted metadata to the Premium Dashboard via the egress proxy. The proxy accepts only these fields: system_id, commit_ref, policy_bundle_version, risk_class, control_pass_rate, control_fail_rate, pending_verifications_count, bundle_checksum, size_bytes, signed_by, timestamp, pass_count, fail_count, trap_frequency, override_rate, eval_set_id, eval_overall_outcome and eval_failed_evaluator_ids. A body with any other key is refused whole.

Request body:

{
  "system_id": "loan-decision-model"
}

Response 200: when no dashboard is configured (PRO_DASHBOARD_URL unset) nothing is sent anywhere; the proxy only confirms that the body is allowed:

{
  "status": "synced",
  "destination": null,
  "fields_validated": true,
  "field_count": 1
}

field_count is the number of fields in the request body. When a dashboard is configured the proxy forwards the body to it and returns the dashboard's own response and status.

Response 403: EGRESS_BLOCKED — the body has a field outside the allowlist, or the dashboard URL is not an allowed destination. The body is {"error_code": "EGRESS_BLOCKED", "message": "...", "category": "policy", "retryable": false, "policy_hash": "sha256:..."}. See Air-gap.

Response 503: DEPENDENCY_UNAVAILABLE — the configured dashboard could not be reached.

GET /v1/status¶

Aggregate status of every downstream service. Probes risk-engine, evidence-vault, doc-generator and egress-proxy and reports each one. This is not a liveness probe; use GET /health for that.

Query parameters:

Response 200: an object with status, service, version, checked_at and a services map with one entry per downstream service. The response fields, the strict flag and how to monitor with them are described in Observability — GET /v1/status.

GET /v1/portfolio¶

List the AI systems on record for the caller's tenant, each with its most recently issued compliance badge. A system appears only once it has at least one badge.

Response 200:

{
  "systems": [
    {
      "system_id": "loan-decision-model",
      "badge_id": "sha256:5b1c8e...",
      "bundle_checksum": "sha256:3e2f1a...",
      "issued_at": "2026-05-25T10:00:00+00:00",
      "status": "compliant"
    }
  ],
  "count": 1
}

Entries are sorted by system_id.

POST /v1/pro/badges/issue¶

Issue a compliance badge for a passing scan status artifact. Idempotent: issuing the same system_id and bundle_checksum again returns the existing badge.

Request body:

{
  "system_id": "loan-decision-model",
  "bundle_checksum": "sha256:3e2f1a...",
  "artifact": {
    "result": "pass",
    "pending_verifications_count": 0
  },
  "signature": null
}

Response 201:

{
  "badge_id": "sha256:5b1c8e...",
  "system_id": "loan-decision-model",
  "issued_at": "2026-05-25T10:00:00+00:00",
  "status_artifact_hash": "sha256:9c1d4f...",
  "created": true
}

created is false when the badge already existed; the status is still 201.

Response 422: the artifact does not meet the issuance criteria, the signature is missing or invalid, or the body failed validation. Returned as {"detail": ...}.

GET /v1/pro/badges/verify/{badgeId}¶

Return a badge's metadata without exposing the raw artifact.

Response 200:

{
  "badge_id": "sha256:5b1c8e...",
  "system_id": "loan-decision-model",
  "bundle_checksum": "sha256:3e2f1a...",
  "issued_at": "2026-05-25T10:00:00+00:00",
  "status_artifact_hash": "sha256:9c1d4f...",
  "valid": true
}

Response 404: no such badge for the caller's tenant. Returned as {"detail": "Badge not found: <badgeId>"}.

GET /v1/pro/badges/{badgeId}/svg¶

Return the badge's SVG markup. The evidence vault serves the badge as image/svg+xml, but the gateway does not forward that body as it is: it wraps the SVG text in a JSON object and returns it as application/json. Like every /v1 endpoint it needs credentials, so the URL cannot be used directly as the src of a README image; fetch it with a credential and use the raw value.

Response 200:

{
  "raw": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"200\" height=\"20\">...</svg>"
}

raw is the complete SVG document as a string.

Response 404: no such badge for the caller's tenant. Returned as {"detail": "Badge not found: <badgeId>"}.

POST /v1/pro/ingest/status-artifact¶

Record a scan status artifact in the evidence ledger (a pro_status_artifact_ingested event). The request goes through the egress proxy to the evidence vault.

Request body:

{
  "system_id": "loan-decision-model",
  "commit_ref": "abc1234",
  "result": "pass",
  "failed_controls": [],
  "pending_verifications_count": 0
}

Response 201:

{
  "event_id": "e1a2b3c4-...",
  "payload_hash": "sha256:9c1d4f..."
}

POST /v1/pro/ingest/dossier-metadata¶

Record dossier metadata in the evidence ledger (a pro_dossier_metadata_ingested event). The request goes through the egress proxy to the evidence vault.

Request body:

{
  "system_id": "loan-decision-model",
  "policy_bundle_version": "2026.05",
  "bundle_checksum": "sha256:3e2f1a...",
  "size_bytes": 48213
}

Response 201: {"event_id": "...", "payload_hash": "sha256:..."}, as for POST /v1/pro/ingest/status-artifact.

POST /v1/pro/ingest/metrics¶

Record compliance metrics in the evidence ledger (a pro_metrics_ingested event). The request goes through the egress proxy to the evidence vault.

Request body:

{
  "system_id": "loan-decision-model",
  "pass_count": 41,
  "fail_count": 2,
  "control_pass_rate": 0.95
}

Response 201: {"event_id": "...", "payload_hash": "sha256:..."}, as for POST /v1/pro/ingest/status-artifact.

Endpoint summary¶