API and integration
ARA exposes a small JSON API so other tools (CALIBRE Governance Fabric, GRC platforms, scripts) can request assessments.
Authentication
Required. Send Authorization: Bearer <ARA_API_KEY> (or X-API-Key).
Endpoints
| Method and path | Purpose |
|---|---|
| POST /api/analyse | Full assessment, synchronous (1 to 4 minutes). Body {"initiative_id", "scenario", "overrides"}. Returns the brief, Structured Findings, overall inherent and residual ratings, the decision, and the assessment id and URL. This is the contract CALIBRE Governance Fabric uses. |
| POST /api/assessments | Same input, asynchronous: returns 202 with an assessment_id. Optional "include_attack": true. |
| GET /api/assessments/{id} | Status, progress and, when complete, the decision, findings and full assessment. |
| GET /a/{id}/redteam.json, .csv | Red-team tests for Secure-RAG Breach Lab (POST /api/targets/{id}/import there). |
| POST /api/adm/test | APP 1.7 test, stateless. Body {"role", "effect", "personal_information", "human_review", "vendor"}. Returns in scope, not in scope or needs legal review, with reasons. |
| GET /api/assessments/{id}/frameworks | Suggested mapping of the assessment's controls to ISO/IEC 42001 Annex A, NIST AI RMF, ISO/IEC 27001:2022 and OWASP LLM 2025 (verify). |
| GET /api/assessments/{id}/versions | Saved versions with SHA-256, and the active sign-off. |
| GET /api/envelopes/{id}?v= | Operating envelope (latest or a given version) with its SHA-256. |
| GET /api/version | Product, version, model configuration (no keys) and whether Secure-RAG is configured. |
| GET /healthz | Health check. |
Connecting CALIBRE Governance Fabric
- In the Fabric's Render environment set ARA_URL to this site's address (no trailing path).
- If this deployment sets ARA_API_KEY, set the same value as ARA_API_KEY in the Fabric (Fabric tool v1.0.9 or later sends it).
- Run a full assessment in the Fabric: findings with source "ara" appear on the initiative page, and the assessment also appears in this library with source "api".
Pushing operating envelopes to the Fabric
Set FABRIC_URL and FABRIC_API_KEY. "Push latest version" on an envelope page sends POST {FABRIC_URL}/api/envelopes with the initiative id, version, SHA-256 and the envelope. The Fabric then checks agent actions against it.
Connecting Secure-RAG
Set SECURE_RAG_URL to Secure-RAG's evidence endpoint, for example https://secure-rag-2.onrender.com/api/query, and SECURE_RAG_TOKEN if Secure-RAG requires one. The Compliance agent then receives retrieved passages.
Decision support only, not legal or regulatory advice. AI-generated ratings and citations must be reviewed by a qualified person before they are relied on.