RAIC REST API Reference
The raic-api/v1 surface exposes tenant-scoped read and write access to AI systems, use cases, risks, controls, suppliers, governance policies, AI Discovery findings, maturity scores, phishing simulations, HIPAA registers, AI Data Governance, the AI catalog, Shadow AI detection, organization setup, Partner client onboarding and the audit log. This page is the public, crawlable mirror of the canonical reference DOCX and the OpenAPI 3.1 spec.
Base URL & spec
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).
Authentication
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. A marketplace connector's token renews itself in its last 14 days withPOST /v1/tokens/rotate. - 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.
Scopes
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.
Endpoint families
- Registry —
/v1/ai-systems,/v1/use-cases,/v1/risks(plus/v1/risks/bulk),/v1/controls,/v1/suppliers. Every register can be listed. AI systems can also be read one at a time (by UUID or system ID). Risks and suppliers can be created, updated and deleted; controls can be updated; use cases can be submitted for intake review (POST /v1/use-cases) and updated. - Policies —
/v1/policiesand/v1/policies/{id}for the governance policy library. - Partners —
POST /v1/msp/clientslets a signed-in Partner admin add a client organization on a package (Core, Compliance or Suite) at the client's employee band and the firm's partner discount (also the Ask RAIC tool for adding clients). API tokens cannot call it. - Organization setup —
/v1/org-setuplets a signed-in OrgAdmin finish the Getting Started checklist (allowed email domains, governance designations, System Register lookups, use case register settings, alert and review cadence, email deliverability). Ask RAIC uses it to run the startup checklist step by step. Inviting team members stays in the app. API tokens cannot call it. - Discovery —
/v1/discovery/appsfor Shadow AI findings and agent signals. - Maturity —
/v1/maturity/snapshotsand/v1/maturity/snapshots/latest(requires?domain=aior?domain=cyber). - HIPAA —
/v1/hipaa/baas,/v1/hipaa/safeguards,/v1/hipaa/breaches(Cyber Compliance Pack, in the Compliance and Suite packages; an Org Admin switches HIPAA on first). - 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/proxyfor in-line allow / mask / block decisions,/v1/data/events(acknowledge with/v1/data/events/{id}/ack),/v1/data/policies(plus/v1/data/policies/simulateto test a payload without enforcing), and/v1/data/vault/{id}. These need the AI Data Governance module, in the Suite package, and answer403 module_not_enabledwithout it. If RAIC could not store part of a flow's record, the ingest and proxy answers list it inpersist_failures; the allow, mask or block decision still stands. - Shadow AI Detection —
/v1/shadow-ai/registry-assets:bulkand/v1/shadow-ai/signatures:bulkfor 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=csvfor a spreadsheet of the failed rows, or?format=csv&rows=allfor every row),/v1/shadow-ai/rulesetfor the published detector config, and/v1/shadow-ai/signatures:retirefor platform tokens to soft-retire up to 20 low-adoption file or hash signatures per call, with one confirmed result per signature./v1/shadow-ai/signatures:resolvelooks up to 100 file hashes against the signature corpus and returns the matching registry asset for each; retired hashes come back as not found. - Audit & health —
/v1/audit,/v1/credentials/health.
Every write requires X-Idempotency-Key (8 to 200 characters, replayed for 24 hours) and accepts X-Dry-Run: 1 for validate-only previews.
AI assistants can call the same endpoints as tools through the RAIC MCP Server.
Rate limits
Platform defaults apply per category (read 120/min, write 20/min, bulk 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.
Webhooks
Tenants can register HTTPS receivers for risk.created, risk.updated, risk.deleted, supplier.created, supplier.updated, supplier.deleted, control.updated, use_case.created, use_case.updated, policy.created, policy.updated, policy.deleted events. Each delivery carries X-RAIC-Signature: sha256= plus the HMAC-SHA256 of the raw body, keyed with your whsec_ signing secret, which RAIC keeps encrypted. Endpoints created before 11/10/2026 are keyed with the lowercase hex SHA-256 digest of the secret until you recreate them. A receiver has 8 seconds to answer 2xx. Failed deliveries retry after 1m / 5m / 30m / 2h / 6h and stop after 5 attempts; you can replay any delivery from the delivery log.
Error envelope
Errors return HTTP 4xx/5xx with a stable code:
{ "data": null, "meta": { ...context }, "error": "insufficient_scope" }Common codes: Unauthorized, token_expired, insufficient_scope (meta.required lists the scopes that would work), validation_failed, missing_idempotency_key, idempotency_key_conflict, not_found and rate_limited. A 429 answers with error, retry_after_seconds, limit and count plus a Retry-After header. See the DOCX reference for the full table.
Plans & versioning
The authenticated API surface — minting rai_* tokens, webhooks, the bulk endpoint and the MCP server — is included in every plan, starting with Core. Questions go to [email protected]. 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.
