API and integration
Authentication and identity
API key required. Send Authorization: Bearer <key>. The key decides the identity; role, department and classification fields in a request are ignored (v2.1 trusted them).
| Identity | Role | Departments | Clearance | How it is used |
|---|---|---|---|---|
| analyst_compliance | analyst | compliance | internal | web page demonstration |
| manager_risk | manager | risk | confidential | web page demonstration |
| manager_security | manager | security | restricted | web page demonstration |
| executive | executive | compliance, risk, privacy, security, procurement | confidential | web page demonstration |
| service_evidence | analyst | compliance, risk, privacy, procurement | internal | SECURE_RAG_TOKEN (ARA, CALIBRE Governance Fabric) |
| admin | admin | compliance, risk, privacy, security, procurement | restricted | API key mapped in SECURE_RAG_API_KEYS only |
Endpoints
All endpoints that take a workspace default to demo. A key written as key:persona@W3 in SECURE_RAG_API_KEYS is limited to workspace W3 (other workspaces return 403).
| Method and path | Purpose |
|---|---|
| POST /api/query | Evidence endpoint, no model call. Body {"query", "top_k", "workspace"}. Returns {"results": [{"source", "text", "score", "url", "doc_id", "document_id", "page", "section", "title", "classification", "sha256", ...}]}. Used by ARA and CALIBRE Governance Fabric. |
| POST /api/ask | Governed answer with evidence, obligations, metrics, answer checks and a claim-by-claim check (claims). |
| GET /api/workspaces | Workspaces visible to the key. |
| POST /api/workspaces/{id}/documents | Upload one file (multipart file plus metadata fields). Needs an administrator key or a key limited to that workspace. |
| GET /api/obligations?workspace= | Obligations register (actor, modality, action, condition, deadline, source), filtered to documents the key may read. |
| POST /api/benchmark/{workspace}?label=&k= | Runs the retrieval benchmark: recall@k, MRR, nDCG@k, abstention accuracy. |
| POST /api/vendor-check | Body {"workspace", "vendor", "apra_regulated"}. Evidence per vendor control: evidenced, unclear, not found, not applicable. Used by ARA vendor due diligence. |
| POST /api/targets/{id}/run | Runs every Breach Lab test of a target. |
| POST /api/targets/{id}/gate | Release gate for CI. HTTP 200 with {"gate": "pass"}, or HTTP 409 with the failing high and critical tests. |
| POST /api/targets/{id}/import | Import red-team prompts (ARA /a/{id}/redteam.json format) as Breach Lab tests. |
| POST /api/findings/{id}/replay | Replays a finding's scenario; issues Proof-of-Fix Records for tests that now pass. |
| GET /api/proofs/{id} | Proof-of-Fix Record with its SHA-256 and an integrity flag. /lab/proofs/{id}.json downloads the canonical record. |
| GET /api/passports/{id} | Trust Passport with live claim statuses. |
| GET /api/coverage?workspace= | Areas and knowledge gaps. |
| GET /api/audit, /api/audit/verify | Recent events; chain verification. |
| GET /api/attacks, POST /api/attack, POST /api/attack-suite | Baseline security tests (deterministic, end to end). |
| POST /api/attack-live | One live model challenge (needs a provider; requires the API key when one is set). |
| GET /api/status, /api/version, /healthz | Configuration (no secrets), version, health. |
Release gate in a CI pipeline
curl -sf -X POST "https://<this site>/api/targets/T1/gate" -H "Authorization: Bearer $SECURE_RAG_KEY" || exit 1
-f makes curl fail on HTTP 409, which stops the pipeline when a high or critical test fails.
Notifications
A target can post to a webhook when a run fails or regresses. When FABRIC_URL and FABRIC_API_KEY are set and the target names a Fabric initiative, each run is reported to the Fabric's POST /api/test-results, so a failing control re-opens the linked approval condition.
Connecting ARA and CALIBRE Governance Fabric
- Set SECURE_RAG_TOKEN here to a long random value.
- In ARA and in the Fabric set SECURE_RAG_URL=https://<this site>/api/query and the same SECURE_RAG_TOKEN.
- Check: the Fabric header shows "Secure-RAG: connected", and a full assessment lists findings with source "secure_rag"; ARA's compliance section says "Grounded in N Secure-RAG passages".
Answers come only from the governed library and are decision support, not legal advice. Verify regulatory content against the regulator's current publication.