Skip to content
DashboardWebsite

API Overview

Interactive documentation is available at /v1/docs (Swagger UI) and /v1/redoc once the server is running.


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.


ProtocolWhereUse case
REST (HTTP/JSON)the API, /v1Automation, CI, custom scripts
MCP (Streamable HTTP)the MCP service, mcp.<your-domain> or /platform-mcp on the API hostAn agent running analyses or managing OpenTremor
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.


Prefixes are relative to /v1, except /health, /scim/v2, /reports/{token} and the webhook and callback routes, which are at the root.

TagPrefixPurpose
health/health, /health/readyLiveness and readiness probes (no auth)
capabilities/capabilitiesWhat this deployment offers: mode, mail, installed product (any principal)
session/auth/register, /auth/session…, /auth/me…, password reset and email verificationHuman registration, login and logout; session introspection for the dashboard (no API-key auth)
auth/auth/keys, /permissionsService 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}/acceptPreview is public; accept requires a session — see Invitations
packs/packs, /{pack}/…, /{changeset}/…/autoDiscovery, 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/demoLoad 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/statusThe 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/callbackNotification channels (Slack, Microsoft Teams, email, webhook), each subscribing to its own events; the guided Slack install
metrics/metrics/…, /analysis/metrics/summaryTelemetry, key usage and the audit log, for one org
pricing/pricing, /admin/pricingThe instance’s price list — see Pricing
admin/admin/…Platform-wide, cross-tenant operator views — requires is_superadmin, not any org role. See Platform Admin.

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-Key header or ?api_key=) — machine principal for CI/MCP clients, created via POST /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 via POST /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-Org header), capped by the token’s read, write or admin scope. It cannot change the account. See Access Tokens for Agents.
  • Session cookie (mcp_session, set by POST /v1/auth/session) — human principal for interactive/dashboard use, obtained via POST /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.

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:

PermissionDefault roleAuditorGrants
agent_access:manageadminChoose whether members’ access tokens act in the organization, and how far.
analysis:readmember✓List packs and their rules; read changesets, resources, dumps and reports.
analysis:runmemberIngest input, run an analysis, and submit a resource’s analysis.
api_keys:manageadminCreate, list and revoke the organization’s API keys.
audit:readadmin✓Read and export the organization’s audit log.
billing:manageadminSet the organization’s monthly spend cap.
billing:readviewer✓See this month’s usage, spend and trial.
demo:managememberLoad or remove the organization’s demo analysis.
feedback:readmember✓Read reviewer verdicts, rule health and rule proposals.
feedback:writememberRecord a verdict on a finding.
findings:readmember✓List findings.
findings:summaryviewer✓See finding counts by status and severity.
findings:triagememberChange a finding’s status.
integrations:manageadminConnect, register and remove the GitHub and GitLab integrations.
invites:manageadminCreate, list and revoke invitation links.
jobs:listviewer✓List the organization’s analysis jobs.
jobs:readmember✓Read one analysis job’s status.
jobs:runmemberCancel or retry an analysis job.
llm_connections:manageadminCreate, change, test and delete LLM connections.
llm_connections:readmember✓List the organization’s LLM connections.
members:manageadminAdd, change, suspend and remove members; reset their password or 2FA.
members:readmember✓List the organization’s members.
metrics:readadmin✓Read the organization’s telemetry and API-key usage.
models:readmember✓List the models an analysis may use.
notifications:manageadminCreate, change, test and delete notification channels.
notifications:readmember✓List the events a notification channel can subscribe to.
org:leaveviewerLeave the organization.
org:readviewer✓See the organization’s details.
packs:manageadminSee and change which packs the organization has enabled.
products:manageadminCreate, change and delete products.
products:readviewer✓List the organization’s products.
report_links:manageadminSet how long public report links stay valid.
report_templates:manageadminCreate, change, delete and seed report templates.
report_templates:readmember✓List, read and preview report templates.
repositories:manageadminSync the repository list, assign repositories to teams and set the ownership rules.
repositories:readviewer✓List the repositories the organization’s integrations reach.
roles:manageadminCreate, change and delete the organization’s custom roles.
roles:readmember✓List the organization’s roles and what each grants.
rule_categories:manageadminCreate, change, delete and seed rule categories.
rule_categories:readmember✓List and read rule categories.
rule_proposals:manageadminRefresh, apply and dismiss rule proposals.
rules:manageadminCreate, change, delete and seed custom rules.
rules:readmember✓List and read custom rules.
scim:manageadminConfigure SCIM provisioning and rotate its token.
sso:manageadminConfigure the organization’s SSO connection.
teams:manageadminCreate, rename and delete teams; change their members.
teams:readmember✓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.

org_name and invite_token are both optional and mutually exclusive — send one, the other, or neither:

Terminal window
# 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" \
-d '{"email": "[email protected]", "password": "at-least-8-chars", "org_name": "My Org"}'
# → sets the mcp_session cookie; you now own a brand-new organization
Terminal window
# Join an org via an invitation link instead — see Invitations below
curl -X POST http://localhost:8000/v1/auth/register \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "at-least-8-chars", "invite_token": "xK9mZpQ..."}'
Terminal window
# 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" \
-d '{"email": "[email protected]", "password": "at-least-8-chars"}'

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.

Terminal window
curl -X POST http://localhost:8000/v1/auth/session \
-H "Content-Type: application/json" \
-d '{"email": "[email protected]", "password": "at-least-8-chars"}' \
-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.

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.

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:

Terminal window
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.

In the dashboard: Organization → Access → Service Accounts, the row’s delete action.

Terminal window
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.

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.


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: 4f6c1b0e9d2a4e3f8b7c6d5e4f3a2b1c

All errors return JSON:

{"detail": "human-readable message"}
StatusMeaning
400Bad request (e.g. unknown filter field)
401Missing or invalid credentials (API key or session), or an invalid GitHub webhook signature
402Org’s monthly LLM spend cap already met/exceeded (/analyze pre-flight check — see Billing / quota)
403Authenticated, 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
404Resource / pack not found, or a cross-org access attempt
409Conflict, 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
413Input too large (exceeds server.max_input_size_mb)
422Schema validation error or invalid analysis payload
500Unhandled server error. The body adds request_id, the request’s ID
501Pack not yet implemented, or the GitHub manifest-flow trigger without server.public_base_url set
502LLM 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