RAIC REST API Reference

All traffic should target the custom domain:

https://app.rhindoncyber.com/api/public/v1

The OpenAPI 3.1 document is served at /v1/openapi.json on the same base, and bundled with the SPA at /openapi.json for offline tooling (Postman, Insomnia, OpenAPI Generator, MCP).

Two equivalent auth mechanisms are supported on every route:

• API tokens — reveal-once rai_* bearers minted by an OrgAdmin at /admin/api-tokens. SHA-256 hashed at rest. Scope-, expiry-, and IP-restricted; rotatable.
• Supabase JWT — for in-app integrations using a logged-in user's access token.

Every request is scoped to the calling tenant. Super Admin impersonation does not extend through API tokens.

• raic:registry:read — Read systems, use-cases, risks, controls, suppliers (AI + Cyber).
• raic:registry:write — Create + update registry rows (AI + Cyber).
• raic:registry:delete — Delete registry rows (separated from write).
• raic:reports:read — Read scheduled-report exports + maturity snapshots.
• raic:discovery:read — Read AI Discovery findings + agent signals.
• raic:audit:read — Read tenant audit log.
• raic:webhooks:manage — Create/update/revoke webhook endpoints. JWT only. (JWT only — not mintable on a token)
• raic:tokens:manage — Mint/revoke/rotate API tokens. JWT only. (JWT only — not mintable on a token)
• raic:cyber:read — Cyber-only read. Server forces domain=cyber on every list.
• raic:cyber:write — Cyber-only write. Server forces domain=cyber on every payload.
• raic:catalog:read — Read the global AI detection catalog and the caller's own curator submissions (submitter-scoped).
• raic:catalog:write — Queue curator submissions (new / patch / retire) into the SuperAdmin triage queue. Never writes the live catalog directly.
• raic:data:read — Read AI data flows, findings, and DLP events (no payload samples).
• raic:data:write — Ingest data flows and submit content for classification and policy decisions.
• raic:data:policies:manage — Create, version, simulate, and graduate data governance policies and packs.
• raic:vault:read — Read decrypted retained payload samples from the payload vault. JWT only. (JWT only — not mintable on a token)
• raic:shadow-ai:read — Read bulk ingestion job status and the published detection ruleset.
• raic:shadow-ai:write — Bulk-ingest registry assets and detection signatures produced by an approved curator.

raic:* is a synthetic super-scope returned only for Super Admin JWT callers; it is never mintable on a rai_* token.

• Registry — /v1/ai-systems, /v1/use-cases, /v1/risks (plus /v1/risks/bulk), /v1/controls, /v1/suppliers. List, read-by-id, create, update, delete.
• Policies — /v1/policies and /v1/policies/{id} for the governance policy library.
• Discovery — /v1/discovery/apps for Shadow AI findings and agent signals.
• Maturity — /v1/maturity/snapshots and /v1/maturity/snapshots/latest (requires ?domain=ai or ?domain=cyber).
• HIPAA — /v1/hipaa/baas, /v1/hipaa/safeguards, /v1/hipaa/breaches (Professional + Enterprise HIPAA module).
• Phishing — /v1/phishing/simulations, /v1/phishing/simulations/{id}, /v1/phishing/click-rate.
• AI Catalog Curator — /v1/ai-catalog/entries, /v1/ai-catalog/entries/lookup, /v1/ai-catalog/candidates, /v1/ai-catalog/candidates/{id}.
• AI Data Governance — /v1/data/flows (plus /v1/data/flows/batch), /v1/data/proxy for in-line allow / mask / block decisions, /v1/data/events, /v1/data/policies, and /v1/data/vault/{id} (Enterprise module).
• Shadow AI Detection — /v1/shadow-ai/registry-assets:bulk and /v1/shadow-ai/signatures:bulk for machine-scale detection ingestion (up to 1,000 rows per call, answered with a job id), /v1/shadow-ai/jobs/{jobId} to poll per-row results (append ?format=csv for a spreadsheet of the failed rows, or ?format=csv&rows=all for every row), and /v1/shadow-ai/ruleset for the published detector config.
• Audit & health — /v1/audit, /v1/credentials/health.

Every write accepts X-Idempotency-Key (24-hour replay) and X-Dry-Run: 1 for validate-only previews.

Platform defaults apply per category (read 120/min, write 20/min, bulk 5/min, heavy 10/min, admin 5/min, machine ingestion 120/min). OrgAdmins can additionally cap any individual token to a custom RPM and / or daily ceiling on /admin/api-tokens. Exceeding either returns HTTP 429 with a Retry-After header.

Tenants can register HTTPS receivers for risk.created, risk.updated, control.updated, usecase.updated, supplier.* events. Deliveries are signed with X-RAIC-Signature (HMAC-SHA256 of the raw body). Failed deliveries retry with exponential backoff (1m / 5m / 30m / 2h / 12h) and are dead-lettered after five attempts.

Errors return HTTP 4xx/5xx with:

{ "data": null, "meta": {}, "error": "human-readable code" }

Common codes: missing_bearer, invalid_token, scope_required, tier_required, validation_failed, rate_limited. See the DOCX reference for the full table.

The authenticated API surface — minting rai_* tokens, webhooks, and the bulk endpoint — requires an Enterprise subscription. All routes are namespaced under /v1 — breaking changes will introduce /v2 and /v1 will remain available for at least 12 months after a v2 release.