Rhindon Cyber logo
    Support & Documentation
    Contact Support

    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 with POST /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/policies and /v1/policies/{id} for the governance policy library.
    • Partners — POST /v1/msp/clients lets 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-setup lets 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/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 (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/proxy for in-line allow / mask / block decisions, /v1/data/events (acknowledge with /v1/data/events/{id}/ack), /v1/data/policies (plus /v1/data/policies/simulate to test a payload without enforcing), and /v1/data/vault/{id}. These need the AI Data Governance module, in the Suite package, and answer 403 module_not_enabled without it. If RAIC could not store part of a flow's record, the ingest and proxy answers list it in persist_failures; the allow, mask or block decision still stands.
    • 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), /v1/shadow-ai/ruleset for the published detector config, and /v1/shadow-ai/signatures:retire for 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:resolve looks 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.