← All documentation

API

The REST API and the MCP server are included in Premium and Enterprise.
They are not in the demo: a key or connection used during the demo is refused
with 403 until your organization chooses a plan. SAML single sign-on works on
both plans and during the demo.

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 → MFA Policy), 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, and whether the Data Processing Agreement has been accepted 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 AI registry: systems, models with their versions, published card versions (never drafts), reviews with their signed decisions, and the risk register.
  • POST /api/v1/ai-systems — propose a system. It is created in the proposed stage, unclassified; 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 breach does.
  • 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 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 and their agreements, AI incidents, evidence metadata, the risk register, training records, your compliance score, the audit log, and the AI registry: systems, models with their versions and evaluation results, published cards, reviews with their signed decisions, and each system's monitoring metrics.

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.

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:

  • an org admin has enabled MCP write access under Settings → API, and
  • the connection was granted write scope at the consent screen.

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.