← All documentation

API

The REST API and the MCP server are included in Premium and Enterprise.
They are not on the Free plan: a key or connection used without a paid plan is
refused with 403 until your organization chooses Premium or Enterprise. SAML
single sign-on and SCIM provisioning are on the paid plans too.

The REST API at /api/v1/ lets external tools read and update your governance data. Authenticate with a Bearer API key:

Authorization: Bearer bsk_...

A key records whether the session that created it had completed multi-factor authentication. If your organization requires MFA (Settings → Sign-in security), keys created from a session without a second factor are refused with 403 until you create a new key from an MFA-verified session — the same rule that applies to browser sessions and to MCP connections.

Scopes

Keys carry explicit scopes. Read scopes (findings:read, assessments:read, remediation:read) gate GET; write scopes (*:write) gate POST/PATCH. Grant only what an integration needs, and set an expiry on write-capable keys.

A scope is necessary but not sufficient, on reads as well as writes. A scope answers "may this key touch findings at all"; it never answers "may this PERSON".

Every call is checked against the key owner's current role, and the check mirrors the corresponding screen in the app: if the owner cannot open a register in the dashboard, their key cannot read it through the API either. So a key owned by a contributor is refused the audit log, the incident register, webhooks, the compliance score and the training endpoints; a key owned by a read-only auditor is refused the remediation register outright, and is refused findings, policies, evidence and assessments unless their auditor grant covers that scope. Findings and remediation are also row-scoped the same way the screens are: a contributor's key returns only records assigned to them.

Writes add two further requirements: the owner must hold an organization-admin role (for assessments and remediation, any non-auditor role), and an org admin must have accepted the Data Processing Agreement for your organization.

Point integrations at a key owned by an organization admin. A key inherits its owner's current role, so moving that person to auditor or contributor narrows what the key can do — reads included.

If any call returns 403 where you expect 200, check the key owner's role, the key's scopes, whether the Data Processing Agreement has been accepted and, for an organization that handles protected health information, whether its business associate agreement has been signed, before regenerating the key. Regenerating does not change what a key is permitted to do.

Reading & writing

  • GET /api/v1/{findings,assessments,remediation} — list with filters + paging (?limit= 1–100, ?offset=).
  • GET /api/v1/{evidence,vendors} — read evidence metadata (never file contents) and vendors with their agreements.
  • GET /api/v1/{ai-systems,models,model-cards,approvals,risks} — the registry: systems (each with its uses_ai and handles_ephi flags; ?flag=ai or ?flag=ephi filters by one), models with their versions, published card versions (never drafts), reviews with their signed decisions, and the risk register.
  • POST /api/v1/ai-systems — add a system. uses_ai defaults to true and handles_ephi to false, and at least one must be true. A system that uses AI is created in the proposed stage, unclassified; one that does not is created in use. The flags are set only here, at creation: changing one later opens or ends a review, so it is done on the system's page. The API never sets a risk tier, a classification or a lifecycle stage.
  • POST /api/v1/model-versions, GET/POST /api/v1/evaluations — for a CI or ML pipeline: register a model version, and record evaluation results against it.
  • GET/POST /api/v1/metrics — monitoring evidence for a deployed system (scopes monitoring:read and monitoring:write). A pipeline posts up to 500 points per request against the metrics the system's owners defined on its page; a point whose external_id was already recorded adds nothing, and one invalid point refuses the whole batch. See the AI systems help for what a point past the action threshold (stored as state breach) does.
  • GET /api/v1/monitoring-plans — each system's monitoring plan: whether one is in force, its published versions (never a draft) and whether its review is due (scope monitoring_plans:read).
  • GET /api/v1/bias-audits — the bias audits recorded for your AI systems (New York City Local Law 144): each audit's next due date, whether it is current, due soon or overdue, and what the record leaves out (scope bias_audits:read).
  • POST /api/v1/risks — create a risk, under the same rules as the form.
  • Approvals are read-only: a decision is signed in the dashboard with a password and a second factor, never through a key.
  • GET /api/v1/webhooks — list endpoints; ?catalog=1 lists subscribable events.
  • POST /api/v1/remediation — create a task (returns 201).
  • PATCH /api/v1/{findings,remediation,assessments} — update by id.
  • POST/PATCH/DELETE /api/v1/webhooks — manage webhook endpoints.

Findings and assessments are update-only via the API (findings are generated from assessments; assessments need question/scope setup done in the app).

Conventions

Responses are JSON with a data array plus count/limit/offset (findings and remediation also include total). Errors return a non-2xx status with a single error key; an unhandled 500 additionally carries message and request_id. Keys are rate-limited to 100 requests/minute (see the X-RateLimit-* response headers). Create and scope keys in Settings → API once your organization is on a paid plan.

Connect an AI assistant (MCP)

MCP (Model Context Protocol) lets an AI harness — Claude Desktop, Claude Code, or any MCP client — read your governance data, and, only if you switch it on, update a few records.

The server URL is:

https://backsplice.ai/api/mcp

There is no key to paste. The client discovers the server, registers itself, and sends you through Backsplice login and a consent screen; it then receives a short-lived token bound to your account and your permissions. Revoke it at any time under Settings → API.

Claude Desktop

  1. Open Settings → Connectors → Add custom connector.
  2. Give it a name (for example, Backsplice) and paste the server URL above.
  3. Click Add, then Connect. A browser window opens.
  4. Sign in to Backsplice and approve the consent screen. If your organization requires MFA you will be challenged first.
  5. The connector shows as connected, and the tools appear in new chats.

Claude Code

claude mcp add --transport http backsplice https://backsplice.ai/api/mcp

Then run /mcp inside Claude Code and choose Authenticate. The same login and consent screen opens in your browser. claude mcp list shows the connection.

Other MCP clients

Any client supporting remote MCP over HTTP with OAuth 2.1 works. Point it at the server URL; it discovers everything else from /.well-known/oauth-protected-resource. Clients that only speak stdio need a remote-MCP bridge.

What it can read

Findings, assessments, policies, remediation tasks, vendors with a summary of their agreements, incidents, evidence metadata, the risk register and risk analyses, training records, your compliance score, the audit log, requests, the systems register, and the AI registry around it: models with their versions and evaluation results, published cards, reviews with their signed decisions, the dataset register, published impact assessments, management reviews, the human oversight roster, each system's monitoring metrics, its published monitoring plan (never a draft), and the bias audits recorded for each system (New York City Local Law 144). For HIPAA: the device register, the disclosure log, workforce sanctions, breach notifications and vulnerability scans.

The assistant always acts with your own permissions — never more than you can see in the app yourself. If you cannot open a register in the dashboard, the assistant cannot read it either. Every call is recorded in the audit log — including calls that are refused. A read that returns a record holding protected health information (an incident that may hold it, a HIPAA request, the disclosure log, a workforce sanction, which is a disciplinary record that may describe the PHI involved, and breach notifications) also writes a phi.viewed event naming the record by its identifier, as the dashboard does; an API key's reads of those registers write it too.

A connected assistant or an API key reads the free text a person typed (an incident's title, description and notes; a request's references, summary and response) only for an incident recorded as not involving protected health information and a request under no HIPAA type or basis. For an incident where it was involved, is not yet known or was never asked, and for a HIPAA request, those fields are left out and the record says text_withheld; its dates, type, status, severity and the other recorded answers still come back, and a text search of requests never matches one. A remediation task that is a corrective action of such an incident is answered the same way: its title, description and approval notes are left out, it says text_withheld, and the read is recorded as a phi.viewed event. The dashboard shows the whole record.

Write access is off by default

A connected assistant can read your data. It can only change data — update findings, create remediation tasks, add comments, propose an AI system — when both of these are true:

  • a full org admin (never a delegated one) has enabled MCP write access under Settings → API, and
  • the connection was granted write scope at the consent screen.

The same agreements that lock writes in the app lock them here: until the organization has accepted the Data Processing Agreement, and, for an organization that is a covered entity or a business associate, signed its business associate agreement, a write is refused with the same sentence the app shows (proposing a system stays open).

Turning write access back off takes effect immediately, including for connections that already hold write scope. Write actions still prompt you to confirm in the MCP client.

Enable it only if your agreement with the AI client's provider covers sending governance data to that provider. Free-text fields (incident narratives, finding notes, evidence) may contain personal data.

No connection can record a decision: there is no tool that approves or rejects a system, signs a review, sets a risk tier or classification, or publishes a card.

Platform administrators

A superadmin can additionally work across organizations:

  • platform_orgs and platform_posture return every organization on the platform with its plan, status, compliance score and finding, incident and task counts. These are aggregates only — no notes, narratives or evidence ever cross a tenant boundary this way. The scope is requested explicitly and is named on the consent screen; it is never granted by default.
  • org_id on any ordinary tool acts on one named organization instead of your own, with full detail. One organization per call, so no single response mixes two tenants' records. If the connection was also granted write scope, org_id applies to the write tools too — so it can update findings, create tasks and add comments in another organization, not only read them.

Both are refused for everyone else: a non-superadmin passing org_id simply reads their own organization, and the platform tools are not offered at all.

See web/docs/CONTRACT-mcp.md for the full security model.