API Overview
Interactive documentation is available at /v1/docs (Swagger UI) and /v1/redoc once the server is running.
Base URL
Section titled “Base URL”http://<host>:<port>/v1/Default: http://localhost:8000/v1/
Every REST route is under /v1. A few routes stay at the root because a third party or a posted
link holds their URL: health checks, Prometheus /metrics, webhooks, OAuth, OIDC and SAML
callbacks, SCIM and public report links. See Versioning and deprecation.
Access modes
Section titled “Access modes”| Protocol | Where | Use case |
|---|---|---|
| REST (HTTP/JSON) | the API, /v1 | Automation, CI, custom scripts |
| MCP (Streamable HTTP) | the MCP service, mcp.<your-domain> or /platform-mcp on the API host | An agent running analyses or managing OpenTremor |
LLM workflow
Section titled “LLM workflow”flowchart TD
B["<b>1.</b> POST /v1/{pack}/{changeset}/ingest\nSend the raw diff\nReceive a receipt with the revision_id"] --> C
C{{"<b>2.</b> POST /v1/{changeset}/claims\n→ a batch of units and their rules"}}
C -->|status: units| E["a. Analyse each unit\nagainst rulesets[unit.ruleset_id]"]
E --> F["b. POST /v1/{changeset}/analyses\n→ store the batch"]
F --> C
C -->|status: waiting| C
C -->|status: done| G["<b>3.</b> GET /v1/changesets/{changeset}/report\nRetrieve the report:\nMarkdown, HTML or JSON"]
Server-side alternative: POST /v1/{pack}/{changeset}/analyze runs the workflow above on the server. The caller supplies an LLM provider and model, with an API key or one stored for the organization, and gets the report directly for small inputs or a job to poll for large inputs. See POST /v1/{pack}/{changeset}/analyze.
Router groups
Section titled “Router groups”Prefixes are relative to /v1, except /health, /scim/v2, /reports/{token} and the webhook
and callback routes, which are at the root.
| Tag | Prefix | Purpose |
|---|---|---|
health | /health, /health/ready | Liveness and readiness probes (no auth) |
capabilities | /capabilities | What this deployment offers: mode, mail, installed product (any principal) |
session | /auth/register, /auth/session…, /auth/me…, password reset and email verification | Human registration, login and logout; session introspection for the dashboard (no API-key auth) |
auth | /auth/keys, /permissions | Service accounts (API keys with an optional IP allowlist and scopes); the permission catalogue |
social-login | /auth/providers, /auth/oauth/…, /auth/me/identities… | Google and Microsoft sign-in, and linked identities |
sso | /orgs/{org_id}/sso, /auth/sso/… | Per-org OIDC or SAML connection, plus the public login flow — see Single sign-on |
scim | /orgs/{org_id}/scim, /scim/v2/{org_id}/… | SCIM provisioning config, and the SCIM protocol itself (its own bearer token) |
orgs | /orgs/… | Org info, members, pack enablement, billing quota/usage, report-link TTL |
roles | /orgs/{org_id}/roles… | Built-in and custom roles |
teams | /orgs/{org_id}/teams/… | Teams and their members. Teams grant no access; they own repositories and can scope notification channels |
invitations | /invite/{token}, /invite/{token}/accept | Preview is public; accept requires a session — see Invitations |
packs | /packs, /{pack}/…, /{changeset}/…/auto | Discovery, rules, ingest, server-side analyze, auto-routing |
resources | /resource/…, /{changeset}/…, /changesets… | Resources, the client-led loop, changesets and revisions, reports, the merge gate |
reports | /reports/{token} | Public, time-limited HTML report access (no auth — see Report links) |
jobs | /jobs/… | Analysis jobs: list, status, cancel, retry |
findings | /findings/… | Finding triage — list, summary, PATCH status |
detection-rules | /detection-rules/{rule_id} | The rule behind an agent-manipulation finding: its AGENT-* rule_id, or an atr:<rule_id> tag |
review-feedback | /feedback, /rule-health, /rule-proposals… | Reviewer verdicts, per-rule precision, proposed rule changes |
demo | /demo | Load or remove the demo analysis |
custom-rules | /orgs/{org_id}/rules/… | Custom rules, including the enabled/requires_review toggles |
rule-categories | /orgs/{org_id}/rule-categories/… | The org’s rule categories |
report-templates | /orgs/{org_id}/report-templates… | Custom Jinja2 report templates, seed-builtin, preview |
llm-connections | /orgs/{org_id}/llm-connections… | Stored LLM endpoints and keys |
llm-models | /models, /admin/models…, /llm/status | The allowed-models catalog; whether LLM features are on |
integrations | /orgs/{org_id}/integrations/github…, /orgs/{org_id}/integrations/gitlab…, /integrations/github/…, /integrations/gitlab/webhook/{webhook_id} | GitHub App and self-managed GitLab: connect, the custom-App manifest flow, the public webhook receivers |
products | /orgs/{org_id}/products… | Products: named groups of repositories whose teams review all of them — see Review routing |
repositories | /orgs/{org_id}/repositories… | The repositories the integrations reach, their teams, and the ownership rules — see Review routing |
notifications | /notifications/events, /orgs/{org_id}/notifications/…, /notifications/slack/callback | Notification channels (Slack, Microsoft Teams, email, webhook), each subscribing to its own events; the guided Slack install |
metrics | /metrics/…, /analysis/metrics/summary | Telemetry, key usage and the audit log, for one org |
pricing | /pricing, /admin/pricing | The instance’s price list — see Pricing |
admin | /admin/… | Platform-wide, cross-tenant operator views — requires is_superadmin, not any org role. See Platform Admin. |
Authentication
Section titled “Authentication”Every request resolves to a principal bound to exactly one organization (org_id) — there is no cross-org access without switching credentials. Three kinds of principal exist, all checked against the same role model:
- API key (
X-API-Keyheader or?api_key=) — machine principal for CI/MCP clients, created viaPOST /v1/auth/keys. Over MCP, send it in the header. Each tool call runs in the key’s organization, with its role. - Access token (
Authorization: Bearer ot_pat_…, created viaPOST /v1/auth/me/access-tokens) — a person’s credential for an agent or a script. It acts as that person in one of their orgs (X-OpenTremor-Orgheader), capped by the token’sread,writeoradminscope. It cannot change the account. See Access Tokens for Agents. - Session cookie (
mcp_session, set byPOST /v1/auth/session) — human principal for interactive/dashboard use, obtained viaPOST /v1/auth/register,POST /v1/auth/session, or a completed SSO login (GET /auth/sso/callback) — all three set the same cookie, so nothing downstream distinguishes how a session was obtained.
Authentication is optional and controlled by auth.api_key in the config file — when null (the default), the server runs as an anonymous owner of a default org with no authentication, suitable for local dev or private networks only.
Roles and permissions
Section titled “Roles and permissions”Every org-scoped endpoint requires one permission, never a role name. A role is a set of
permissions. Four built-in roles form a ladder, viewer < member < admin < owner. Each holds every
permission whose default role it reaches; owner holds them all. The fifth built-in role,
auditor, sits off the ladder: it holds every permission marked in the Auditor column and
nothing that changes state. Give it to a security team or to the API key that feeds a SIEM. The
sixth, pipeline, also sits off the ladder and only an API key can hold it. It holds what a CI job
or an agent needs to run analyses, and nothing else: analysis:read, analysis:run, jobs:list,
jobs:read and jobs:run. It is the default role of POST /v1/auth/keys. An
org can also define custom roles from any set of permissions (see
Roles), and an API key can be narrowed to a subset of its
role’s permissions with scopes.
A request whose role lacks the permission gets 403. GET /v1/permissions returns this catalogue at
run time:
| Permission | Default role | Auditor | Grants |
|---|---|---|---|
agent_access:manage | admin | Choose whether members’ access tokens act in the organization, and how far. | |
analysis:read | member | ✓ | List packs and their rules; read changesets, resources, dumps and reports. |
analysis:run | member | Ingest input, run an analysis, and submit a resource’s analysis. | |
api_keys:manage | admin | Create, list and revoke the organization’s API keys. | |
audit:read | admin | ✓ | Read and export the organization’s audit log. |
billing:manage | admin | Set the organization’s monthly spend cap. | |
billing:read | viewer | ✓ | See this month’s usage, spend and trial. |
demo:manage | member | Load or remove the organization’s demo analysis. | |
feedback:read | member | ✓ | Read reviewer verdicts, rule health and rule proposals. |
feedback:write | member | Record a verdict on a finding. | |
findings:read | member | ✓ | List findings. |
findings:summary | viewer | ✓ | See finding counts by status and severity. |
findings:triage | member | Change a finding’s status. | |
integrations:manage | admin | Connect, register and remove the GitHub and GitLab integrations. | |
invites:manage | admin | Create, list and revoke invitation links. | |
jobs:list | viewer | ✓ | List the organization’s analysis jobs. |
jobs:read | member | ✓ | Read one analysis job’s status. |
jobs:run | member | Cancel or retry an analysis job. | |
llm_connections:manage | admin | Create, change, test and delete LLM connections. | |
llm_connections:read | member | ✓ | List the organization’s LLM connections. |
members:manage | admin | Add, change, suspend and remove members; reset their password or 2FA. | |
members:read | member | ✓ | List the organization’s members. |
metrics:read | admin | ✓ | Read the organization’s telemetry and API-key usage. |
models:read | member | ✓ | List the models an analysis may use. |
notifications:manage | admin | Create, change, test and delete notification channels. | |
notifications:read | member | ✓ | List the events a notification channel can subscribe to. |
org:leave | viewer | Leave the organization. | |
org:read | viewer | ✓ | See the organization’s details. |
packs:manage | admin | See and change which packs the organization has enabled. | |
products:manage | admin | Create, change and delete products. | |
products:read | viewer | ✓ | List the organization’s products. |
report_links:manage | admin | Set how long public report links stay valid. | |
report_templates:manage | admin | Create, change, delete and seed report templates. | |
report_templates:read | member | ✓ | List, read and preview report templates. |
repositories:manage | admin | Sync the repository list, assign repositories to teams and set the ownership rules. | |
repositories:read | viewer | ✓ | List the repositories the organization’s integrations reach. |
roles:manage | admin | Create, change and delete the organization’s custom roles. | |
roles:read | member | ✓ | List the organization’s roles and what each grants. |
rule_categories:manage | admin | Create, change, delete and seed rule categories. | |
rule_categories:read | member | ✓ | List and read rule categories. |
rule_proposals:manage | admin | Refresh, apply and dismiss rule proposals. | |
rules:manage | admin | Create, change, delete and seed custom rules. | |
rules:read | member | ✓ | List and read custom rules. |
scim:manage | admin | Configure SCIM provisioning and rotate its token. | |
sso:manage | admin | Configure the organization’s SSO connection. | |
teams:manage | admin | Create, rename and delete teams; change their members. | |
teams:read | member | ✓ | List teams and their members. |
is_superadmin is a separate axis, not a fifth role above owner. It answers “can this principal see across every org,” which owning even every org you belong to doesn’t imply — a user can be owner of three orgs and a superadmin of none. Gates only /admin/…. See Platform Admin.
Registering and logging in (human users)
Section titled “Registering and logging in (human users)”org_name and invite_token are both optional and mutually exclusive — send one, the
other, or neither:
# Create a new org, owned by you (the original, still-default behavior)curl -X POST http://localhost:8000/v1/auth/register \ -H "Content-Type: application/json" \# → sets the mcp_session cookie; you now own a brand-new organization# Join an org via an invitation link instead — see Invitations belowcurl -X POST http://localhost:8000/v1/auth/register \ -H "Content-Type: application/json" \# Neither — an org-less account. Every org-scoped endpoint 403s until you# create an org (POST /v1/orgs) or accept an invite.curl -X POST http://localhost:8000/v1/auth/register \ -H "Content-Type: application/json" \When the operator requires terms, GET /v1/auth/registration-options returns them under terms, and
every mode also needs "accepted_terms_version" set to that version — 400 otherwise. See
Requiring your terms at sign-up.
curl -X POST http://localhost:8000/v1/auth/session \ -H "Content-Type: application/json" \ -c cookies.txt# → 200 even for an org-less account (org_id/role null in the response) —# this used to 401 with "no organization membership"; org-less is now a# real, intended account state, not an error.An already-registered, org-less account “graduates” by calling POST /v1/orgs (create a
new org, same endpoint an existing user calls to add a second one) or by opening an
invitation link — see Invitations.
Bootstrap admin key
Section titled “Bootstrap admin key”auth.api_key in the config is the bootstrap admin key. It is permanent, never stored in the database, cannot be revoked, and always resolves to the default org as owner. Treat it like a root password and keep it secret.
Creating service accounts
Section titled “Creating service accounts”In the dashboard: Organization → Access → Service Accounts.
Use an admin/owner credential (bootstrap key or a logged-in session) to create runtime keys — “service accounts” in dashboard terms — scoped to that credential’s org, optionally restricted to a set of source IPs:
curl -X POST http://localhost:8000/v1/auth/keys \ -H "X-API-Key: <admin-key>" \ -H "Content-Type: application/json" \ -d '{"role": "member", "name": "ci-pipeline", "ip_allowlist": ["203.0.113.0/24"]}'{ "key_id": "3f4a...", "key": "xK9mZ...", "role": "member", "name": "ci-pipeline", "ip_allowlist": ["203.0.113.0/24"], "created_at": "2026-01-01T00:00:00Z"}The raw key is returned once — store it securely. name and ip_allowlist are both
optional; a request using this key from outside ip_allowlist gets 403 (the key is valid, just
not usable from there) rather than the 401 an unrecognised key gets.
Revoking a key
Section titled “Revoking a key”In the dashboard: Organization → Access → Service Accounts, the row’s delete action.
curl -X DELETE http://localhost:8000/v1/auth/keys/<key_id> \ -H "X-API-Key: <admin-key>"Only a key belonging to the caller’s own org can be revoked — attempting to revoke another org’s key returns 404, not 403 (it gives no signal that the key exists at all).
See Auth endpoints for the full API reference.
Single sign-on (SSO)
Section titled “Single sign-on (SSO)”In the dashboard: Organization → Access → SSO.
Each org can connect its own identity provider over OIDC or SAML 2.0 instead of relying on passwords. POST/GET/PATCH/DELETE /v1/orgs/{org_id}/sso (org-admin) manages the connection. POST /v1/auth/sso/discover and GET /v1/auth/sso/{org_id}/start start the login for both protocols. OIDC returns to GET /auth/sso/callback. SAML posts to POST /auth/sso/saml/{org_id}/acs, which continues at GET /auth/sso/saml/complete in the same browser. All these endpoints are public: the caller isn’t authenticated yet. GET /v1/orgs/{org_id}/sso/service-provider and GET /auth/sso/saml/{org_id}/metadata provide the SAML values to enter in the IdP. A completed login resolves the account by the IdP’s identity, never by email: the iss and sub claims for OIDC, the entity ID and NameID for SAML. If the email belongs to an account that isn’t linked yet, the login is refused. The owner signs in and links through GET /v1/auth/sso/{org_id}/link. A new email gets a new account, and the account joins the org with the connection’s default_role if it isn’t a member yet. An existing membership is never downgraded. See Quick Start: SSO & SCIM — Single sign-on for the setup walkthrough and API Endpoints — SSO for the full request/response reference.
Request ID
Section titled “Request ID”Every response includes an X-Request-ID header. Supply your own to correlate a call with the spans and audit events it produces. It must be a UUID or 32 hex characters; any other value is replaced with a fresh ID, which the response returns:
X-Request-ID: 4f6c1b0e9d2a4e3f8b7c6d5e4f3a2b1cError responses
Section titled “Error responses”All errors return JSON:
{"detail": "human-readable message"}| Status | Meaning |
|---|---|
| 400 | Bad request (e.g. unknown filter field) |
| 401 | Missing or invalid credentials (API key or session), or an invalid GitHub webhook signature |
| 402 | Org’s monthly LLM spend cap already met/exceeded (/analyze pre-flight check — see Billing / quota) |
| 403 | Authenticated, but the role or the key’s scopes lack the endpoint’s permission; or an SSO login whose asserted email’s domain isn’t in the connection’s allowed_domains |
| 404 | Resource / pack not found, or a cross-org access attempt |
| 409 | Conflict, such as a duplicate key or a resource that cannot be changed in its current state; a duplicate key during ingest is safe to ignore |
| 413 | Input too large (exceeds server.max_input_size_mb) |
| 422 | Schema validation error or invalid analysis payload |
| 500 | Unhandled server error. The body adds request_id, the request’s ID |
| 501 | Pack not yet implemented, or the GitHub manifest-flow trigger without server.public_base_url set |
| 502 | LLM provider returned output that couldn’t be parsed (/analyze sync path only); an SSO identity provider was unreachable during login (GET /v1/auth/sso/{org_id}/start); or POST /v1/admin/storage/prepare-mongodb couldn’t reach the target MongoDB |