Endpoints: Integrations, Resources & Reports
Integrations
Section titled “Integrations”GitHub and self-managed GitLab. Each org connects GitHub through its own GitHub App, registered with the manifest flow; its credentials are encrypted per org, and GitHub’s signed installation webhook sets its installation_id. There is no platform-wide App. On a pull request (or merge request), each changed file is routed to the pack that reads it, and the result is posted back as a comment and a commit status.
GET /integrations/github/manifest/callback
Section titled “GET /integrations/github/manifest/callback”GitHub App manifest flow callback
Public, authenticated by its state: GitHub redirects the browser here with ?code=&state= after the admin creates the org’s App. The single-use state token, minted by POST /orgs/{org_id}/integrations/github/manifest, identifies the org and admin. The callback exchanges code for the new App’s identity, creates the org’s integration with it (encrypted) and the LLM settings from the flow’s start, then redirects to {dashboard_base_url or public_base_url}/integrations/github?app_created=1.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
code | string | yes | |
state | string | yes |
200307— App created, credentials stored, redirected to the dashboard400— Invalid, expired or already usedstate, or the code exchange with GitHub failed
POST /integrations/github/webhook
Section titled “POST /integrations/github/webhook”GitHub App webhook receiver
Verified via the X-Hub-Signature-256 header, not session/API-key auth. Each org’s App has its own webhook secret, so the org is identified before verification — from installation.id (or installation.app_id, for the first installation event a new App receives) in the as-yet-unverified body — only to select the secret to verify against. The signature check gates every action. A delivery no org matches is acknowledged with 200 and ignored. Only pull_request opened/synchronize/reopened/ready_for_review events trigger analysis. A draft on a repository without review_drafts: true gets a pending commit status and no job (200); ready_for_review queues one only on such a repository. installation created/deleted events record or clear installation_id and add or remove the installation’s repositories in the org’s inventory; installation_repositories events add and remove repositories there; a push to the default branch that changes a file a knowledge source reads starts a sync of that repository’s sources; everything else is acknowledged with 200 and ignored.
Each pull_request event also adds its repository to the org’s list or refreshes its name. A queued job’s trigger is "scm_webhook" and its external_ref is {"provider": "github", "repo": "owner/repo", "pr_number": 42}.
The commit status posted back is failure if an open finding is CRITICAL or HIGH; pending if no finding blocks by severity but a finding is needs_review. A person has not decided yet, so the pull request should not merge. Otherwise, the status is success. Acknowledged, suppressed and false-positive findings never block. Triage through PATCH /findings/{resource_hash}/{rule_id} reposts the status against the same commit, so clearing the last held finding turns the check green without another push.
When the org’s monthly budget is spent, or the integration’s LLM connection is missing or has no key, the job fails with a clear error and makes no GitHub call: no comment, no commit status.
Response 202 (application/json) — Analysis job queued
{ "job_id": "b7e2...", "status": "queued"}200— Ignored, or aninstallation/installation_repositoriesevent acknowledged401— Missing or invalidX-Hub-Signature-256for the resolved secret
POST /integrations/gitlab/webhook/{webhook_id}
Section titled “POST /integrations/gitlab/webhook/{webhook_id}”GitLab webhook receiver (public, secret-verified)
Public, secret-verified: the URL each project’s webhook points at. GitLab deliveries carry nothing that identifies an integration, so the URL does. A delivery is accepted with a valid Standard Webhooks signature (webhook-id, webhook-timestamp, webhook-signature; the secret set as the hook’s signing token; at most 5 minutes old) or, unsigned, with the secret itself in X-Gitlab-Token.
- A
Merge Request Hookwhose action isopen,reopenorupdatewitholdrev(a push; a title edit has none), or anupdatethat takes it out of draft, queues a review. A draft on a repository withoutreview_drafts: truegets a pending commit status and no job (200); leaving draft queues one only on such a repository. The job’striggeris"scm_webhook", itsexternal_refis{"provider": "gitlab", "repo": "group/project", "pr_number": <iid>, "head_sha": "…"}, and its changeset isgl-{project_id}-{iid}. - A
Note Hookfor a person’s new note on a merge request is recorded as reviewer feedback. The token’s own bot notes, system notes, notes on other objects and edits are ignored. - A push to the default branch that changes a file a knowledge source reads starts a sync of that project’s sources.
- Anything else is acknowledged and ignored.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
webhook_id | string | yes |
Response 200 (application/json) — Note recorded as feedback, event ignored, or the org is locked
{ "detail": "recorded", "verdict": "rejected", "trusted": true}Response 202 (application/json) — Review queued
{ "job_id": "b7e2...", "status": "queued"}401— Unknown integration, or a bad signature or token
GET /v1/orgs/{org_id}/code-suggestions
Section titled “GET /v1/orgs/{org_id}/code-suggestions”Get the code suggestion settings
Whether code suggestions are posted on pull requests, from which severity, and how many per push.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "enabled": false, "min_severity": "HIGH", "max_per_review": 10}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | Post code suggestions on pull requests. A repository can override this setting either way. |
min_severity | "CRITICAL" | "HIGH" | "MEDIUM" | no | Only findings at this severity or above get a suggestion. |
max_per_review | integer | no | At most this many suggestions per push. The rest keep their written next step. |
PUT /v1/orgs/{org_id}/code-suggestions
Section titled “PUT /v1/orgs/{org_id}/code-suggestions”Replace the code suggestion settings
With enabled, each pull request review posts inline suggestions on lines the pull request added, for findings at min_severity or above, at most max_per_review per push. A person applies them; OpenTremor never commits. Each suggestion is one more LLM call on the review’s connection and counts against the monthly budget. On a pull request from an author without write access, each suggestion carries a warning. A repository’s own code_suggestions takes precedence over enabled.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "enabled": false, "min_severity": "HIGH", "max_per_review": 10}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | Post code suggestions on pull requests. A repository can override this setting either way. |
min_severity | "CRITICAL" | "HIGH" | "MEDIUM" | no | Only findings at this severity or above get a suggestion. |
max_per_review | integer | no | At most this many suggestions per push. The rest keep their written next step. |
Response 200 (application/json)
{ "enabled": false, "min_severity": "HIGH", "max_per_review": 10}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | Post code suggestions on pull requests. A repository can override this setting either way. |
min_severity | "CRITICAL" | "HIGH" | "MEDIUM" | no | Only findings at this severity or above get a suggestion. |
max_per_review | integer | no | At most this many suggestions per push. The rest keep their written next step. |
GET /v1/orgs/{org_id}/integrations/github
Section titled “GET /v1/orgs/{org_id}/integrations/github”Get this org’s GitHub App integration config
The org’s GitHub App integration. Requires the org’s admin role. installation_id is null until the App is installed on a repository. github_app never carries the private key or the webhook secret.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "installation_id": "string", "llm_backend": "string", "connection_id": "string", "model": "string", "created_at": "2026-01-01T00:00:00Z", "github_app": { "app_id": "string", "app_slug": "string", "html_url": "string" }}| Field | Type | Required | Description |
|---|---|---|---|
installation_id | string | null | no | Set by GitHub’s installation webhook once the App is installed on a repository. Null until then. |
llm_backend | string | yes | |
connection_id | string | yes | The stored connection webhook runs use |
model | string | yes | |
created_at | string (date-time) | yes | |
github_app | GitHubAppInfo | yes | Public-safe view of the org’s GitHub App — never the private key or webhook secret. |
404— No App yet
PUT /v1/orgs/{org_id}/integrations/github
Section titled “PUT /v1/orgs/{org_id}/integrations/github”Change the LLM settings of this org’s GitHub integration
Changes the LLM connection and model of the org’s GitHub integration. Requires the org’s admin role. Uses the same body and checks as the manifest request, without app_name. The integration itself is created by the manifest flow.
In the dashboard: Analysis settings on Organization → Connections → GitHub.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "connection_id": "string", "model": "string"}| Field | Type | Required | Description |
|---|---|---|---|
connection_id | string | yes | The stored LLM connection webhook-triggered analysis calls (GET /orgs/{org_id}/llm-connections). A PR gate has no caller to supply a key, so the connection must hold one. |
model | string | yes | Provider-specific model name |
Response 200 (application/json)
{ "installation_id": "string", "llm_backend": "string", "connection_id": "string", "model": "string", "created_at": "2026-01-01T00:00:00Z", "github_app": { "app_id": "string", "app_slug": "string", "html_url": "string" }}| Field | Type | Required | Description |
|---|---|---|---|
installation_id | string | null | no | Set by GitHub’s installation webhook once the App is installed on a repository. Null until then. |
llm_backend | string | yes | |
connection_id | string | yes | The stored connection webhook runs use |
model | string | yes | |
created_at | string (date-time) | yes | |
github_app | GitHubAppInfo | yes | Public-safe view of the org’s GitHub App — never the private key or webhook secret. |
400— The connection or the model is rejected404— No App yet
DELETE /v1/orgs/{org_id}/integrations/github
Section titled “DELETE /v1/orgs/{org_id}/integrations/github”Disconnect this org’s GitHub App integration
Disconnects everything: installation, LLM settings and App credentials. Requires the org’s admin role. Every GitHub repository is marked removed and keeps its teams for a reconnect. The App itself stays on GitHub.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Nothing connected
GET /v1/orgs/{org_id}/integrations/github/app-name
Section titled “GET /v1/orgs/{org_id}/integrations/github/app-name”Suggest a name for the org’s GitHub App, or check one
Without name, returns a generated App name: opentremor-<org name, up to 16 characters>-<6 hex>, at most 34 characters. With name, returns whether GitHub is likely to accept it. Requires the org’s admin role.
result is available (no check found the name), taken (another org here, or a public GitHub App, has it), warning (a GitHub account has this login; GitHub accepts it only if the App is created under that account) or unknown (GitHub did not answer, for example, because it exceeded its limit of 60 unauthenticated requests per hour). reason explains every result except available. A private App is invisible to the check.
In the dashboard: the App name field on Organization → Connections → GitHub.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
name | string | null | no |
Response 200 (application/json)
{ "name": "string"}| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | A generated App name, unique enough not to collide on GitHub |
POST /v1/orgs/{org_id}/integrations/github/manifest
Section titled “POST /v1/orgs/{org_id}/integrations/github/manifest”Start the GitHub App manifest flow for the org’s own App
Returns a manifest + one-time state token to POST to GitHub’s App-creation form (github.com/settings/apps/new) as a real top-level browser form submit — GitHub creates the App under the admin’s own account/org and redirects back to the public manifest callback with a code that completes the exchange. The LLM settings are checked here (400) and stored with the state, so the integration is created configured. app_name is checked like GET …/app-name; 409 when it is taken. Without it, a name is generated. Starting again replaces the org’s integration once the new App is created.
connection_id names a stored LLM connection that holds a key (a webhook never has an inline one), and model is checked against the allowed-models catalog now and again before every webhook-triggered run. state is a single-use, 10-minute CSRF token: POST manifest and state to target_url as a real top-level form submission, never a fetch.
In the dashboard: Create GitHub App on Organization → Connections → GitHub.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "connection_id": "string", "model": "string", "app_name": "string"}| Field | Type | Required | Description |
|---|---|---|---|
connection_id | string | yes | The stored LLM connection webhook-triggered analysis calls (GET /orgs/{org_id}/llm-connections). A PR gate has no caller to supply a key, so the connection must hold one. |
model | string | yes | Provider-specific model name |
app_name | string | null | no | The name to give the App on GitHub. Omit it to use a generated one (GET …/github/app-name). |
Response 200 (application/json)
{ "manifest": {}, "state": "string", "target_url": "string"}| Field | Type | Required | Description |
|---|---|---|---|
manifest | object | yes | Manifest JSON to POST to GitHub’s App-creation form |
state | string | yes | CSRF state token — round-tripped by GitHub as the state query param |
target_url | string | yes | Where to POST the manifest form (github.com’s app-creation page) |
400— Bad Request409— Conflict501—server.public_base_urlis not set: the manifest’s webhook and redirect URLs need a reachable HTTPS address
GET /v1/orgs/{org_id}/integrations/gitlab
Section titled “GET /v1/orgs/{org_id}/integrations/gitlab”Get this org’s GitLab integration
The org’s GitLab integration, without webhook_secret. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "base_url": "string", "bot_username": "string", "has_tls_ca": false, "token_expires_at": "string", "webhook_url": "string", "llm_backend": "string", "connection_id": "string", "model": "string", "created_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
base_url | string | yes | |
bot_username | string | yes | The token’s bot user — the author of our notes |
has_tls_ca | boolean | no | Whether the org supplied its own CA bundle |
token_expires_at | string | null | no | When the access token stops working |
webhook_url | string | null | no | Paste into each project’s Settings → Webhooks. Null until the deployment’s server.public_base_url is set |
llm_backend | string | yes | |
connection_id | string | yes | |
model | string | yes | |
created_at | string (date-time) | yes |
404— Nothing connected
POST /v1/orgs/{org_id}/integrations/gitlab
Section titled “POST /v1/orgs/{org_id}/integrations/gitlab”Connect a self-managed GitLab group to this org
Connects a self-managed GitLab group or updates the connection. Requires integrations:manage (admin). base_url must pass the deployment’s gitlab.egress policy. The token (a group access token, role Developer, scope api) is checked against GitLab before anything is stored and is never returned.
tls_ca_pem is the CA the instance’s certificate chains to, for GitLab behind a company CA. It is encrypted and never returned; has_tls_ca says whether one is set. On an update, omit it to keep the stored one, or send "" to remove it. Without one, gitlab.ca_bundle or the system trust store is used.
webhook_secret is returned on the first connect only. Connecting again to rotate the token, for example, keeps the webhook URL and secret, so the projects’ hooks keep working, and returns webhook_secret: null. webhook_url is null until server.public_base_url is set.
In the dashboard: Organization → Connections → GitLab.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "base_url": "string", "access_token": "string", "connection_id": "string", "model": "string", "tls_ca_pem": "string"}| Field | Type | Required | Description |
|---|---|---|---|
base_url | string | yes | The GitLab instance’s root URL, e.g. https://gitlab.example.com. Must be allowed by the deployment’s gitlab.egress policy. |
access_token | string | yes | A group access token: role Developer, scope api. Write-only — never returned. GitLab requires an expiry date, at most a year out. |
connection_id | string | yes | The stored LLM connection webhook-triggered analysis calls. |
model | string | yes | Provider-specific model name |
tls_ca_pem | string | null | no | PEM bundle of the CA(s) your GitLab’s certificate chains to, for an instance behind a company CA. Stored encrypted, never returned. On an update: omit it to keep the stored one, send an empty string to remove it. Without one, the deployment’s own CA bundle or the system store is used. |
Response 201 (application/json) — Connected or updated
{ "base_url": "string", "bot_username": "string", "has_tls_ca": false, "token_expires_at": "string", "webhook_url": "string", "llm_backend": "string", "connection_id": "string", "model": "string", "created_at": "2026-01-01T00:00:00Z", "webhook_secret": "string"}| Field | Type | Required | Description |
|---|---|---|---|
base_url | string | yes | |
bot_username | string | yes | The token’s bot user — the author of our notes |
has_tls_ca | boolean | no | Whether the org supplied its own CA bundle |
token_expires_at | string | null | no | When the access token stops working |
webhook_url | string | null | no | Paste into each project’s Settings → Webhooks. Null until the deployment’s server.public_base_url is set |
llm_backend | string | yes | |
connection_id | string | yes | |
model | string | yes | |
created_at | string (date-time) | yes | |
webhook_secret | string | null | yes | Shown on the first connect only. Paste it as each webhook’s Secret token (or as its Signing token to have deliveries signed). Null when an existing integration was updated: its URL and secret are kept, so the projects’ hooks keep working. |
400— The integration is off (gitlab.egress.enabled), the URL is not allowed,tls_ca_pemis not usable PEM, GitLab refused the token or could not be reached (including a certificate error), or the model is not allowed
DELETE /v1/orgs/{org_id}/integrations/gitlab
Section titled “DELETE /v1/orgs/{org_id}/integrations/gitlab”Disconnect this org’s GitLab integration
Disconnects GitLab. Requires the org’s admin role. The projects’ webhooks are refused from then on (401), and every GitLab repository is marked removed and keeps its teams for a reconnect.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Nothing connected
GET /v1/orgs/{org_id}/integrations/gitlab/availability
Section titled “GET /v1/orgs/{org_id}/integrations/gitlab/availability”Whether this deployment offers the GitLab integration
Whether this deployment offers the GitLab integration: false until a platform admin turns on gitlab.egress.enabled, so a client can report that instead of letting a connect fail. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "enabled": true}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | yes | Whether an operator turned the GitLab integration on |
GET /v1/orgs/{org_id}/integrations/jira/availability
Section titled “GET /v1/orgs/{org_id}/integrations/jira/availability”Whether this deployment offers the Jira integration, and whether this org uses it
enabled is false until a platform admin turns it on with jira.enabled, so a client can say so instead of letting a connect attempt fail. Readable by anyone who reads findings: the findings list uses it to offer Create Jira issue.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "enabled": true, "connected": true}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | yes | Whether a platform admin turned the Jira integration on |
connected | boolean | yes | Whether this org has a Jira integration that is not paused. With enabled, whether a finding’s issue can be created now. |
GET /v1/orgs/{org_id}/integrations/jira
Section titled “GET /v1/orgs/{org_id}/integrations/jira”Get this org’s Jira integration
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "base_url": "string", "flavor": "cloud", "email": "string", "account_name": "string", "has_tls_ca": false, "default_target": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] }, "team_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "product_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "priority_by_severity": { "key": "string" }, "transitions": { "done": "string", "wont_do": "string", "reopen": "string" }, "rules": [ { "status": "needs_review", "min_severity": "HIGH", "applies_since": "2026-01-01T00:00:00Z" } ], "include_details": true, "enabled": true, "sync": { "last_sync_at": "2026-01-01T00:00:00Z", "consecutive_failures": 0, "next_attempt_at": "2026-01-01T00:00:00Z", "last_error": "string" }, "created_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
base_url | string | yes | |
flavor | "cloud" | "data_center" | yes | |
email | string | null | yes | |
account_name | string | null | no | The credential’s Jira account, as Jira names it |
has_tls_ca | boolean | no | |
default_target | JiraTarget | yes | Where a new issue goes. |
team_targets | object | no | Team id → target |
product_targets | object | no | Product id → target |
priority_by_severity | object | no | |
transitions | JiraTransitions | yes | Transition names to use. A missing one is chosen by the status category it leads to. |
rules | JiraRule[] | yes | |
include_details | boolean | yes | |
enabled | boolean | yes | |
sync | JiraSyncState | yes | |
created_at | string (date-time) | yes |
404— Not Found
POST /v1/orgs/{org_id}/integrations/jira
Section titled “POST /v1/orgs/{org_id}/integrations/jira”Connect a Jira site to this org, or update it
Checks the URL against the deployment’s jira.egress policy, the credential against Jira (/myself) and the default target’s project, then stores them. On an update, omit api_token and tls_ca_pem to keep the stored ones. Team and product targets are kept; they have their own routes. A rule added here applies to findings that reach its status from now on: use backfill for older ones.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "base_url": "string", "flavor": "cloud", "email": "string", "api_token": "string", "tls_ca_pem": "string", "default_target": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] }, "priority_by_severity": { "key": "string" }, "transitions": { "done": "string", "wont_do": "string", "reopen": "string" }, "rules": [ { "status": "needs_review", "min_severity": "HIGH" } ], "include_details": false, "enabled": true}| Field | Type | Required | Description |
|---|---|---|---|
base_url | string | yes | The site’s root URL, e.g. https://acme.atlassian.net. Must be allowed by the deployment’s jira.egress policy. |
flavor | "cloud" | "data_center" | yes | cloud (REST v3) or data_center (REST v2) |
email | string | null | no | Cloud only: the email of the account the API token belongs to |
api_token | string | null | no | Cloud: an API token. Data Center: a personal access token. Write-only. Required on the first connect. |
tls_ca_pem | string | null | no | Data Center only: PEM bundle of the CA(s) the site’s certificate chains to. Stored encrypted, never returned. Omit it to keep the stored one, send an empty string to remove it. |
default_target | JiraTarget | yes | Where a new issue goes. |
priority_by_severity | object | no | Severity → Jira priority name. A severity left out sets no priority. |
transitions | JiraTransitions | no | Transition names to use. A missing one is chosen by the status category it leads to. |
rules | JiraRuleInput[] | no | When an issue is created without a click. Empty: only by a click. |
include_details | boolean | no | Off: an issue carries title, rule, severity, resource and a dashboard link. On: also the analysis’s explanation and suggested next step. |
enabled | boolean | no | Off pauses this org’s sync. Nothing is deleted. |
Response 201 (application/json)
{ "base_url": "string", "flavor": "cloud", "email": "string", "account_name": "string", "has_tls_ca": false, "default_target": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] }, "team_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "product_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "priority_by_severity": { "key": "string" }, "transitions": { "done": "string", "wont_do": "string", "reopen": "string" }, "rules": [ { "status": "needs_review", "min_severity": "HIGH", "applies_since": "2026-01-01T00:00:00Z" } ], "include_details": true, "enabled": true, "sync": { "last_sync_at": "2026-01-01T00:00:00Z", "consecutive_failures": 0, "next_attempt_at": "2026-01-01T00:00:00Z", "last_error": "string" }, "created_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
base_url | string | yes | |
flavor | "cloud" | "data_center" | yes | |
email | string | null | yes | |
account_name | string | null | no | The credential’s Jira account, as Jira names it |
has_tls_ca | boolean | no | |
default_target | JiraTarget | yes | Where a new issue goes. |
team_targets | object | no | Team id → target |
product_targets | object | no | Product id → target |
priority_by_severity | object | no | |
transitions | JiraTransitions | yes | Transition names to use. A missing one is chosen by the status category it leads to. |
rules | JiraRule[] | yes | |
include_details | boolean | yes | |
enabled | boolean | yes | |
sync | JiraSyncState | yes | |
created_at | string (date-time) | yes |
400— Bad Request403— Forbidden
DELETE /v1/orgs/{org_id}/integrations/jira
Section titled “DELETE /v1/orgs/{org_id}/integrations/jira”Disconnect this org’s Jira integration
Removes the site, the credential, the targets and every finding’s link to its issue. The issues stay in Jira as they are. Allowed while Jira is turned off.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Not Found
POST /v1/orgs/{org_id}/integrations/jira/test
Section titled “POST /v1/orgs/{org_id}/integrations/jira/test”Check the credential and every target
Calls Jira as the sync would: the credential, then for each target its project, its issue type, and the fields Jira requires on create that OpenTremor does not fill. problems names each one that would stop an issue from being created.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "ok": true, "account_name": "string", "problems": [ "string" ]}| Field | Type | Required | Description |
|---|---|---|---|
ok | boolean | yes | |
account_name | string | null | no | |
problems | string[] | no | What would stop an issue from being created |
403— Forbidden404— Not Found
PUT /v1/orgs/{org_id}/integrations/jira/products/{product_id}
Section titled “PUT /v1/orgs/{org_id}/integrations/jira/products/{product_id}”Send a product’s findings to its own Jira target
A new issue goes to the target of the first product its finding was seen in, else of its first assigned team, else to the default target. Chosen once, when the issue is created. The project is checked against Jira first.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
product_id | string | yes |
Request body (application/json)
{ "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ]}| Field | Type | Required | Description |
|---|---|---|---|
project_key | string | yes | e.g. SEC |
issue_type | string | no | The issue type’s name |
labels | string[] | no | Added to every issue, on top of opentremor and the finding’s own label |
components | string[] | no | Component names |
Response 200 (application/json)
{ "base_url": "string", "flavor": "cloud", "email": "string", "account_name": "string", "has_tls_ca": false, "default_target": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] }, "team_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "product_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "priority_by_severity": { "key": "string" }, "transitions": { "done": "string", "wont_do": "string", "reopen": "string" }, "rules": [ { "status": "needs_review", "min_severity": "HIGH", "applies_since": "2026-01-01T00:00:00Z" } ], "include_details": true, "enabled": true, "sync": { "last_sync_at": "2026-01-01T00:00:00Z", "consecutive_failures": 0, "next_attempt_at": "2026-01-01T00:00:00Z", "last_error": "string" }, "created_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
base_url | string | yes | |
flavor | "cloud" | "data_center" | yes | |
email | string | null | yes | |
account_name | string | null | no | The credential’s Jira account, as Jira names it |
has_tls_ca | boolean | no | |
default_target | JiraTarget | yes | Where a new issue goes. |
team_targets | object | no | Team id → target |
product_targets | object | no | Product id → target |
priority_by_severity | object | no | |
transitions | JiraTransitions | yes | Transition names to use. A missing one is chosen by the status category it leads to. |
rules | JiraRule[] | yes | |
include_details | boolean | yes | |
enabled | boolean | yes | |
sync | JiraSyncState | yes | |
created_at | string (date-time) | yes |
400— Bad Request403— Forbidden404— Not Found
DELETE /v1/orgs/{org_id}/integrations/jira/products/{product_id}
Section titled “DELETE /v1/orgs/{org_id}/integrations/jira/products/{product_id}”Remove a product’s Jira target
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
product_id | string | yes |
Response 200 (application/json)
{ "base_url": "string", "flavor": "cloud", "email": "string", "account_name": "string", "has_tls_ca": false, "default_target": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] }, "team_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "product_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "priority_by_severity": { "key": "string" }, "transitions": { "done": "string", "wont_do": "string", "reopen": "string" }, "rules": [ { "status": "needs_review", "min_severity": "HIGH", "applies_since": "2026-01-01T00:00:00Z" } ], "include_details": true, "enabled": true, "sync": { "last_sync_at": "2026-01-01T00:00:00Z", "consecutive_failures": 0, "next_attempt_at": "2026-01-01T00:00:00Z", "last_error": "string" }, "created_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
base_url | string | yes | |
flavor | "cloud" | "data_center" | yes | |
email | string | null | yes | |
account_name | string | null | no | The credential’s Jira account, as Jira names it |
has_tls_ca | boolean | no | |
default_target | JiraTarget | yes | Where a new issue goes. |
team_targets | object | no | Team id → target |
product_targets | object | no | Product id → target |
priority_by_severity | object | no | |
transitions | JiraTransitions | yes | Transition names to use. A missing one is chosen by the status category it leads to. |
rules | JiraRule[] | yes | |
include_details | boolean | yes | |
enabled | boolean | yes | |
sync | JiraSyncState | yes | |
created_at | string (date-time) | yes |
403— Forbidden404— Not Found
PUT /v1/orgs/{org_id}/integrations/jira/teams/{team_id}
Section titled “PUT /v1/orgs/{org_id}/integrations/jira/teams/{team_id}”Send a team’s findings to its own Jira target
Used when none of the finding’s products has a target. The project is checked against Jira first.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
team_id | string | yes |
Request body (application/json)
{ "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ]}| Field | Type | Required | Description |
|---|---|---|---|
project_key | string | yes | e.g. SEC |
issue_type | string | no | The issue type’s name |
labels | string[] | no | Added to every issue, on top of opentremor and the finding’s own label |
components | string[] | no | Component names |
Response 200 (application/json)
{ "base_url": "string", "flavor": "cloud", "email": "string", "account_name": "string", "has_tls_ca": false, "default_target": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] }, "team_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "product_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "priority_by_severity": { "key": "string" }, "transitions": { "done": "string", "wont_do": "string", "reopen": "string" }, "rules": [ { "status": "needs_review", "min_severity": "HIGH", "applies_since": "2026-01-01T00:00:00Z" } ], "include_details": true, "enabled": true, "sync": { "last_sync_at": "2026-01-01T00:00:00Z", "consecutive_failures": 0, "next_attempt_at": "2026-01-01T00:00:00Z", "last_error": "string" }, "created_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
base_url | string | yes | |
flavor | "cloud" | "data_center" | yes | |
email | string | null | yes | |
account_name | string | null | no | The credential’s Jira account, as Jira names it |
has_tls_ca | boolean | no | |
default_target | JiraTarget | yes | Where a new issue goes. |
team_targets | object | no | Team id → target |
product_targets | object | no | Product id → target |
priority_by_severity | object | no | |
transitions | JiraTransitions | yes | Transition names to use. A missing one is chosen by the status category it leads to. |
rules | JiraRule[] | yes | |
include_details | boolean | yes | |
enabled | boolean | yes | |
sync | JiraSyncState | yes | |
created_at | string (date-time) | yes |
400— Bad Request403— Forbidden404— Not Found
DELETE /v1/orgs/{org_id}/integrations/jira/teams/{team_id}
Section titled “DELETE /v1/orgs/{org_id}/integrations/jira/teams/{team_id}”Remove a team’s Jira target
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
team_id | string | yes |
Response 200 (application/json)
{ "base_url": "string", "flavor": "cloud", "email": "string", "account_name": "string", "has_tls_ca": false, "default_target": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] }, "team_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "product_targets": { "key": { "project_key": "string", "issue_type": "Bug", "labels": [ "string" ], "components": [ "string" ] } }, "priority_by_severity": { "key": "string" }, "transitions": { "done": "string", "wont_do": "string", "reopen": "string" }, "rules": [ { "status": "needs_review", "min_severity": "HIGH", "applies_since": "2026-01-01T00:00:00Z" } ], "include_details": true, "enabled": true, "sync": { "last_sync_at": "2026-01-01T00:00:00Z", "consecutive_failures": 0, "next_attempt_at": "2026-01-01T00:00:00Z", "last_error": "string" }, "created_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
base_url | string | yes | |
flavor | "cloud" | "data_center" | yes | |
email | string | null | yes | |
account_name | string | null | no | The credential’s Jira account, as Jira names it |
has_tls_ca | boolean | no | |
default_target | JiraTarget | yes | Where a new issue goes. |
team_targets | object | no | Team id → target |
product_targets | object | no | Product id → target |
priority_by_severity | object | no | |
transitions | JiraTransitions | yes | Transition names to use. A missing one is chosen by the status category it leads to. |
rules | JiraRule[] | yes | |
include_details | boolean | yes | |
enabled | boolean | yes | |
sync | JiraSyncState | yes | |
created_at | string (date-time) | yes |
403— Forbidden404— Not Found
POST /v1/orgs/{org_id}/integrations/jira/backfill
Section titled “POST /v1/orgs/{org_id}/integrations/jira/backfill”Apply the rules to findings that reached their status before the rules existed
Counts the findings the rules match that have no issue yet. Without dry_run, the rules then cover them, and the sync creates their issues over the next ticks, jira.batch_size at a time.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
dry_run | boolean | no | Only count |
Response 200 (application/json)
{ "findings": 0, "applied": true}| Field | Type | Required | Description |
|---|---|---|---|
findings | integer | yes | Findings the rules match that have no issue yet |
applied | boolean | yes | False for a dry run |
403— Forbidden404— Not Found
Repositories
Section titled “Repositories”Every repository the org’s GitHub App installation and GitLab token reach, and the teams that review each one. A repository is keyed by its host and the host’s own id (external_id: the GitHub repository id, the GitLab project id); a rename changes full_name, never the key. Reads need repositories:read (viewer and up); writes need repositories:manage (admin) and record an audit event.
GET /v1/orgs/{org_id}/repositories/ownership
Section titled “GET /v1/orgs/{org_id}/repositories/ownership”Get the ownership rules and the default review team
The ownership rules and the default review team. pattern is a glob on the repository’s full name, matched case-insensitively; rules are tried in order and the first match wins. Besides team_ids, a rule can set product_id, rule_variants and enabled_packs. Each field fills only what the repository has not set; a rule never replaces a person’s choice.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "rules": [ { "pattern": "string", "team_ids": [ "string" ], "product_id": "string", "rule_variants": { "key": "string" }, "enabled_packs": [ "string" ], "knowledge": { "sources": [ { "kind": "adr", "paths": [ null ], "applies_to": "repository" } ] }, "review_drafts": true } ], "default_review_team_id": "string"}| Field | Type | Required | Description |
|---|---|---|---|
rules | OwnershipRule[] | no | Tried in order; the first whose pattern matches gives a new repository its teams. A rule only fills an unowned repository, never replaces teams a person set. |
default_review_team_id | string | null | no | Reviews a repository with no team at review time. Never written onto the repository, so changing it re-routes every unowned repository at once. |
PUT /v1/orgs/{org_id}/repositories/ownership
Section titled “PUT /v1/orgs/{org_id}/repositories/ownership”Replace the ownership rules and the default review team
Rules are tried in order on every repository the inventory discovers; the first match gives it its teams. Saving rules changes no existing repository — POST …/ownership/apply runs them over the unowned ones. Every team id must be one of this org’s teams.
The default review team applies at review time to every repository with no team, so changing it reroutes them at once.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "rules": [ { "pattern": "string", "team_ids": [ "string" ], "product_id": "string", "rule_variants": { "key": "string" }, "enabled_packs": [ "string" ], "knowledge": { "sources": [ { "kind": "adr", "paths": [ null ], "applies_to": "repository" } ] }, "review_drafts": true } ], "default_review_team_id": "string"}| Field | Type | Required | Description |
|---|---|---|---|
rules | OwnershipRule[] | no | Tried in order; the first whose pattern matches gives a new repository its teams. A rule only fills an unowned repository, never replaces teams a person set. |
default_review_team_id | string | null | no | Reviews a repository with no team at review time. Never written onto the repository, so changing it re-routes every unowned repository at once. |
Response 200 (application/json)
{ "rules": [ { "pattern": "string", "team_ids": [ "string" ], "product_id": "string", "rule_variants": { "key": "string" }, "enabled_packs": [ "string" ], "knowledge": { "sources": [ { "kind": "adr", "paths": [ null ], "applies_to": "repository" } ] }, "review_drafts": true } ], "default_review_team_id": "string"}| Field | Type | Required | Description |
|---|---|---|---|
rules | OwnershipRule[] | no | Tried in order; the first whose pattern matches gives a new repository its teams. A rule only fills an unowned repository, never replaces teams a person set. |
default_review_team_id | string | null | no | Reviews a repository with no team at review time. Never written onto the repository, so changing it re-routes every unowned repository at once. |
POST /v1/orgs/{org_id}/repositories/ownership/apply
Section titled “POST /v1/orgs/{org_id}/repositories/ownership/apply”Give unowned repositories the teams of their first matching rule
Only repositories with no team are touched, including any a person left empty on purpose. Repositories that already have teams keep them.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "assigned": 4}| Field | Type | Required | Description |
|---|---|---|---|
assigned | integer | yes | Unowned repositories a rule gave teams to |
POST /v1/orgs/{org_id}/repositories/bulk
Section titled “POST /v1/orgs/{org_id}/repositories/bulk”Set the teams or the product of several repositories
Sets the same fields as PATCH .../repositories/{provider}/{external_id} on up to 1,000 repositories at once; omitted fields are left alone. Any unknown repository, team, product, pack or variant causes the whole request to fail without changing anything.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ "string" ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true, "repositories": [ { "provider": "github", "external_id": "string" } ]}| Field | Type | Required | Description |
|---|---|---|---|
team_ids | string[] | null | no | The owning teams, replacing the current list. Empty unassigns. |
product_id | string | null | no | The product it belongs to. Null removes it from its product. |
enabled_packs | string[] | null | no | Packs that run here on top of the org’s and the product’s, replacing the current list. Validated against the registered packs. Null clears it. |
rule_variants | object | null | no | Pack name → variant, replacing the whole map. Each variant must be one the pack has. |
llm | RepositoryLlm | null | no | The connection and model for this repository’s reviews. Null goes back to the integration’s. |
knowledge | RepositoryKnowledge | null | no | Files rules are drawn from, replacing the current list. Null stops reading them. |
review_drafts | boolean | null | no | Whether draft pull requests are reviewed. Null goes back to the default: they are not. |
code_suggestions | boolean | null | no | Post code suggestions here, or not, whatever the org’s setting. Null follows the org. |
repositories | RepositoryKey[] | yes |
Response 200 (application/json)
{ "updated": 0}404— An unknown repository
GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}
Section titled “GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}”Get one repository
One repository of the org’s list.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "provider": "github", "external_id": "string", "full_name": "string", "status": "active", "source": "sync", "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "excluded_rules": [ { "rule_id": "string", "reason": "string", "excluded_by": "string", "excluded_at": "2026-01-01T00:00:00Z" } ], "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ "string" ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true, "filled_by": { "team_ids": "string", "product_id": "string", "enabled_packs": "string", "knowledge": "string", "review_drafts": "string", "rule_variants": { "key": "string" } }, "knowledge_sync": { "state": "running", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "commit_sha": "string", "files": 0, "proposals": 0, "truncated": false, "error": "string" }, "scan": { "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "slices_left": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z" }, "suggested_packs": [ "string" ], "suggested_rule_variants": { "key": "string" }, "first_seen_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_pull_request_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | The host’s id for the repository — GitHub repository id, GitLab project id |
full_name | string | yes | As a person writes it: acme/infra, acme/platform/infra |
status | "active" | "removed" | no | |
source | "sync" | "webhook" | yes | |
team_ids | string[] | no | Owning teams. Empty until someone assigns one. |
product_id | string | null | no | The product it belongs to, if any (models/catalog.py) |
enabled_packs | string[] | null | no | Packs that run here on top of the org’s and the product’s. Null until someone sets it. |
rule_variants | object | no | Pack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”} |
excluded_rules | RuleExclusion[] | no | Custom rules turned off here, each with the reason |
llm | RepositoryLlm | null | no | Null: the integration’s connection and model |
knowledge | RepositoryKnowledge | null | no | Files rules are drawn from, such as ADRs. Null: none are read. |
review_drafts | boolean | null | no | Whether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false. |
code_suggestions | boolean | null | no | Post code suggestions on this repository’s pull requests. Null: the org’s setting. |
filled_by | FilledBy | no | The ownership rule pattern that filled each setting of a repository (services/repositories/ownership.py). A setting not listed was set by a person, or never set. |
knowledge_sync | KnowledgeSyncState | null | no | The last sync of those files |
scan | ScanState | null | no | The last scan of the default branch. Null: never scanned. |
suggested_packs | string[] | no | Packs that claim files here but are not enabled for it, from a survey of its file tree or a review’s skipped files. Never enabled on their own: apply or dismiss each. |
suggested_rule_variants | object | no | Pack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it. |
first_seen_at | string (date-time) | yes | |
updated_at | string (date-time) | yes | |
last_pull_request_at | string (date-time) | null | no | When a pull or merge request on this repository last asked for a review |
404— The repository list does not have it
PATCH /v1/orgs/{org_id}/repositories/{provider}/{external_id}
Section titled “PATCH /v1/orgs/{org_id}/repositories/{provider}/{external_id}”Set a repository’s teams or product
Sets any of the repository’s fields; omitted ones are left alone.
team_idsreplaces the owning teams.[]unassigns it: reviews then go to its product’s teams, then the org’s default review team.product_idis the product it belongs to; null removes it from its product.enabled_packs: packs that run here, on top of the org’s and the product’s. Replaces the list; null clears it.rule_variants: pack name → the rule variant to use here, such as{"terraform-plan": "aws"}. Replaces the whole map; null clears it.llm:{"connection_id", "model"}for this repository’s reviews, checked like an integration’s; null goes back to the integration’s.knowledge: the sources rules are drawn from, such as{"sources": [{"kind": "adr", "paths": null, "applies_to": "repository"}]}; null stops reading them.review_drafts: true reviews draft pull requests; false or null skips them until they are marked ready.code_suggestions: post code suggestions on pull requests here, or not; null follows the org’s setting.
A setting that breaks later, such as a deleted connection or a variant a pack dropped, falls back to the default instead of failing a review.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ "string" ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true}| Field | Type | Required | Description |
|---|---|---|---|
team_ids | string[] | null | no | The owning teams, replacing the current list. Empty unassigns. |
product_id | string | null | no | The product it belongs to. Null removes it from its product. |
enabled_packs | string[] | null | no | Packs that run here on top of the org’s and the product’s, replacing the current list. Validated against the registered packs. Null clears it. |
rule_variants | object | null | no | Pack name → variant, replacing the whole map. Each variant must be one the pack has. |
llm | RepositoryLlm | null | no | The connection and model for this repository’s reviews. Null goes back to the integration’s. |
knowledge | RepositoryKnowledge | null | no | Files rules are drawn from, replacing the current list. Null stops reading them. |
review_drafts | boolean | null | no | Whether draft pull requests are reviewed. Null goes back to the default: they are not. |
code_suggestions | boolean | null | no | Post code suggestions here, or not, whatever the org’s setting. Null follows the org. |
Response 200 (application/json)
{ "provider": "github", "external_id": "string", "full_name": "string", "status": "active", "source": "sync", "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "excluded_rules": [ { "rule_id": "string", "reason": "string", "excluded_by": "string", "excluded_at": "2026-01-01T00:00:00Z" } ], "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ "string" ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true, "filled_by": { "team_ids": "string", "product_id": "string", "enabled_packs": "string", "knowledge": "string", "review_drafts": "string", "rule_variants": { "key": "string" } }, "knowledge_sync": { "state": "running", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "commit_sha": "string", "files": 0, "proposals": 0, "truncated": false, "error": "string" }, "scan": { "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "slices_left": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z" }, "suggested_packs": [ "string" ], "suggested_rule_variants": { "key": "string" }, "first_seen_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_pull_request_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | The host’s id for the repository — GitHub repository id, GitLab project id |
full_name | string | yes | As a person writes it: acme/infra, acme/platform/infra |
status | "active" | "removed" | no | |
source | "sync" | "webhook" | yes | |
team_ids | string[] | no | Owning teams. Empty until someone assigns one. |
product_id | string | null | no | The product it belongs to, if any (models/catalog.py) |
enabled_packs | string[] | null | no | Packs that run here on top of the org’s and the product’s. Null until someone sets it. |
rule_variants | object | no | Pack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”} |
excluded_rules | RuleExclusion[] | no | Custom rules turned off here, each with the reason |
llm | RepositoryLlm | null | no | Null: the integration’s connection and model |
knowledge | RepositoryKnowledge | null | no | Files rules are drawn from, such as ADRs. Null: none are read. |
review_drafts | boolean | null | no | Whether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false. |
code_suggestions | boolean | null | no | Post code suggestions on this repository’s pull requests. Null: the org’s setting. |
filled_by | FilledBy | no | The ownership rule pattern that filled each setting of a repository (services/repositories/ownership.py). A setting not listed was set by a person, or never set. |
knowledge_sync | KnowledgeSyncState | null | no | The last sync of those files |
scan | ScanState | null | no | The last scan of the default branch. Null: never scanned. |
suggested_packs | string[] | no | Packs that claim files here but are not enabled for it, from a survey of its file tree or a review’s skipped files. Never enabled on their own: apply or dismiss each. |
suggested_rule_variants | object | no | Pack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it. |
first_seen_at | string (date-time) | yes | |
updated_at | string (date-time) | yes | |
last_pull_request_at | string (date-time) | null | no | When a pull or merge request on this repository last asked for a review |
404— The repository list does not have it
GET /v1/orgs/{org_id}/repositories
Section titled “GET /v1/orgs/{org_id}/repositories”List the org’s repositories
Every repository the org’s GitHub and GitLab integrations have reached, ordered by name. A removed repository stays listed with status: removed; pass status=active to hide it. unowned=true lists the repositories with no team.
Other filters: provider (github, gitlab) and team_id (the repositories that team owns). source says how the list first learned of the repository: sync or webhook. A repository the host stops listing, or one belonging to a disconnected integration, becomes removed and keeps its teams. Teams deleted since then are left out of team_ids.
In the dashboard: Analysis → Repositories.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | null | no | |
status | "active" | "removed" | null | no | |
team_id | string | null | no | Only repositories this team owns |
product_id | string | null | no | Only repositories in this product |
unowned | boolean | no | Only repositories with no team |
Response 200 (application/json)
{ "repositories": [ { "provider": "github", "external_id": "string", "full_name": "string", "status": "active", "source": "sync", "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "excluded_rules": [ { "rule_id": "string", "reason": "string", "excluded_by": "string", "excluded_at": "2026-01-01T00:00:00Z" } ], "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ null ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true, "filled_by": { "team_ids": "string", "product_id": "string", "enabled_packs": "string", "knowledge": "string", "review_drafts": "string", "rule_variants": { "key": "string" } }, "knowledge_sync": { "state": "running", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "commit_sha": "string", "files": 0, "proposals": 0, "truncated": false, "error": "string" }, "scan": { "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": null, "paths": null, "categories": null } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ null ], "categories": [ null ] } ], "slices_left": [ { "pack": "string", "paths": [ null ], "categories": [ null ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z" }, "suggested_packs": [ "string" ], "suggested_rule_variants": { "key": "string" }, "first_seen_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_pull_request_at": "2026-01-01T00:00:00Z" } ]}GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/activity
Section titled “GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/activity”A repository’s open findings and changesets
The repository’s open, needs-review and acknowledged findings by severity, its number of changesets (one per pull request reviewed) and the start date of its newest revision. Its changesets are available at GET /changesets?repository=provider/external_id.
In the dashboard: Analysis → Repositories → a repository → Activity.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "repository": "string", "full_name": "string", "status": "string", "open_findings": { "key": 0 }, "changesets": 0, "last_revision_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
repository | string | yes | provider/external_id |
full_name | string | yes | |
status | string | yes | active, or removed when the host no longer lists it |
open_findings | object | yes | Open, needs-review and acknowledged findings seen in it, by severity |
changesets | integer | yes | Its changesets: one per pull request reviewed |
last_revision_at | string (date-time) | null | yes | When its newest revision started |
404— The repository list does not have it
GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/report
Section titled “GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/report”A repository’s open findings as a report
The repository’s open, needs-review and acknowledged findings and its recent changesets, after the rules with the most findings. include_suppressed=true lists suppressed and false-positive findings too.
format: markdown (default), html, or json for the data the report renders. The response is the report itself. detail=summary keeps CRITICAL and HIGH findings. theme (light or dark) sets the HTML report’s theme. Org report templates apply to changeset reports only.
In the dashboard: Analysis → Repositories → a repository → Report.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
format | ReportOutput | null | no | markdown (default), html or json. The response is the report itself: text/markdown, text/html, or the report data as JSON. |
detail | ReportDetail | no | summary keeps CRITICAL and HIGH findings only. On a changeset report in Markdown, it also uses the short pull request comment layout. |
include_suppressed | boolean | no | Also list findings triaged as suppressed or false positive |
theme | "light" | "dark" | null | no | HTML report theme: light or dark. Follows the reader’s system setting when omitted. |
Response 200 (application/json)
{ "timestamp": "string", "kind": "product", "title": "string", "include_suppressed": true, "totals": { "key": 0 }, "finding_count": 0, "repositories": [ {} ], "top_rules": [ {} ]}| Field | Type | Required | Description |
|---|---|---|---|
timestamp | string | yes | |
kind | "product" | "repository" | yes | |
title | string | yes | |
include_suppressed | boolean | yes | |
totals | object | yes | Findings by severity, worst first |
finding_count | integer | yes | |
repositories | object[] | yes | One section per repository: its activity, findings and recent changesets |
top_rules | object[] | yes | The rules with the most findings |
404— The repository list does not have it
POST /v1/orgs/{org_id}/repositories/sync
Section titled “POST /v1/orgs/{org_id}/repositories/sync”Sync the repository list with the code hosts
Lists every repository the GitHub App installation and the GitLab token can reach, adds the new ones, and marks removed the active ones a host no longer lists. Owners are never changed. A host that cannot be listed reports an error and keeps its repositories as they were; the others still sync.
GitLab lists the projects the token is a member of, excluding archived ones. New repositories go through the ownership rules once, then have their file trees surveyed in the background: the packs that claim files there and are not enabled are stored as suggested_packs. The dashboard calls this right after a code host is connected.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "results": [ { "provider": "github", "listed": 0, "added": 0, "removed": 0, "error": "string" } ]}| Field | Type | Required | Description |
|---|---|---|---|
results | RepositorySyncOutcome[] | yes | One per connected code host |
POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/exclusions/{rule_id}
Section titled “POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/exclusions/{rule_id}”Turn a custom rule off for this repository
The rule stops running on this repository’s pull requests, whatever its scope says. A reason is required; it is shown wherever the exclusion is listed. Excluding a rule again replaces its reason.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
rule_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "reason": "string"}| Field | Type | Required | Description |
|---|---|---|---|
reason | string | yes | Why this rule does not apply here |
Response 200 (application/json)
{ "provider": "github", "external_id": "string", "full_name": "string", "status": "active", "source": "sync", "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "excluded_rules": [ { "rule_id": "string", "reason": "string", "excluded_by": "string", "excluded_at": "2026-01-01T00:00:00Z" } ], "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ "string" ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true, "filled_by": { "team_ids": "string", "product_id": "string", "enabled_packs": "string", "knowledge": "string", "review_drafts": "string", "rule_variants": { "key": "string" } }, "knowledge_sync": { "state": "running", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "commit_sha": "string", "files": 0, "proposals": 0, "truncated": false, "error": "string" }, "scan": { "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "slices_left": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z" }, "suggested_packs": [ "string" ], "suggested_rule_variants": { "key": "string" }, "first_seen_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_pull_request_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | The host’s id for the repository — GitHub repository id, GitLab project id |
full_name | string | yes | As a person writes it: acme/infra, acme/platform/infra |
status | "active" | "removed" | no | |
source | "sync" | "webhook" | yes | |
team_ids | string[] | no | Owning teams. Empty until someone assigns one. |
product_id | string | null | no | The product it belongs to, if any (models/catalog.py) |
enabled_packs | string[] | null | no | Packs that run here on top of the org’s and the product’s. Null until someone sets it. |
rule_variants | object | no | Pack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”} |
excluded_rules | RuleExclusion[] | no | Custom rules turned off here, each with the reason |
llm | RepositoryLlm | null | no | Null: the integration’s connection and model |
knowledge | RepositoryKnowledge | null | no | Files rules are drawn from, such as ADRs. Null: none are read. |
review_drafts | boolean | null | no | Whether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false. |
code_suggestions | boolean | null | no | Post code suggestions on this repository’s pull requests. Null: the org’s setting. |
filled_by | FilledBy | no | The ownership rule pattern that filled each setting of a repository (services/repositories/ownership.py). A setting not listed was set by a person, or never set. |
knowledge_sync | KnowledgeSyncState | null | no | The last sync of those files |
scan | ScanState | null | no | The last scan of the default branch. Null: never scanned. |
suggested_packs | string[] | no | Packs that claim files here but are not enabled for it, from a survey of its file tree or a review’s skipped files. Never enabled on their own: apply or dismiss each. |
suggested_rule_variants | object | no | Pack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it. |
first_seen_at | string (date-time) | yes | |
updated_at | string (date-time) | yes | |
last_pull_request_at | string (date-time) | null | no | When a pull or merge request on this repository last asked for a review |
404— Unknown rule, or the repository list does not have the repository
DELETE /v1/orgs/{org_id}/repositories/{provider}/{external_id}/exclusions/{rule_id}
Section titled “DELETE /v1/orgs/{org_id}/repositories/{provider}/{external_id}/exclusions/{rule_id}”Turn a custom rule back on for this repository
Turns an excluded custom rule back on for this repository.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
rule_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "provider": "github", "external_id": "string", "full_name": "string", "status": "active", "source": "sync", "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "excluded_rules": [ { "rule_id": "string", "reason": "string", "excluded_by": "string", "excluded_at": "2026-01-01T00:00:00Z" } ], "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ "string" ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true, "filled_by": { "team_ids": "string", "product_id": "string", "enabled_packs": "string", "knowledge": "string", "review_drafts": "string", "rule_variants": { "key": "string" } }, "knowledge_sync": { "state": "running", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "commit_sha": "string", "files": 0, "proposals": 0, "truncated": false, "error": "string" }, "scan": { "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "slices_left": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z" }, "suggested_packs": [ "string" ], "suggested_rule_variants": { "key": "string" }, "first_seen_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_pull_request_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | The host’s id for the repository — GitHub repository id, GitLab project id |
full_name | string | yes | As a person writes it: acme/infra, acme/platform/infra |
status | "active" | "removed" | no | |
source | "sync" | "webhook" | yes | |
team_ids | string[] | no | Owning teams. Empty until someone assigns one. |
product_id | string | null | no | The product it belongs to, if any (models/catalog.py) |
enabled_packs | string[] | null | no | Packs that run here on top of the org’s and the product’s. Null until someone sets it. |
rule_variants | object | no | Pack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”} |
excluded_rules | RuleExclusion[] | no | Custom rules turned off here, each with the reason |
llm | RepositoryLlm | null | no | Null: the integration’s connection and model |
knowledge | RepositoryKnowledge | null | no | Files rules are drawn from, such as ADRs. Null: none are read. |
review_drafts | boolean | null | no | Whether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false. |
code_suggestions | boolean | null | no | Post code suggestions on this repository’s pull requests. Null: the org’s setting. |
filled_by | FilledBy | no | The ownership rule pattern that filled each setting of a repository (services/repositories/ownership.py). A setting not listed was set by a person, or never set. |
knowledge_sync | KnowledgeSyncState | null | no | The last sync of those files |
scan | ScanState | null | no | The last scan of the default branch. Null: never scanned. |
suggested_packs | string[] | no | Packs that claim files here but are not enabled for it, from a survey of its file tree or a review’s skipped files. Never enabled on their own: apply or dismiss each. |
suggested_rule_variants | object | no | Pack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it. |
first_seen_at | string (date-time) | yes | |
updated_at | string (date-time) | yes | |
last_pull_request_at | string (date-time) | null | no | When a pull or merge request on this repository last asked for a review |
404— The rule is not excluded here
GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/effective
Section titled “GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/effective”What the next pull request on this repository would run with
What the next pull request on this repository runs with: the owning teams (team_ids, which determine the matching rule scopes), the teams the review goes to (review_team_ids: the owning teams, or the default review team; empty for an org-wide review), the product, the packs (the org’s, the product’s and the repository’s) and the variant each uses, the custom rules that apply after scope and exclusions, and the LLM. The review job builds these settings with the same function, so they cannot disagree with what runs. A rule is listed only when one of its packs runs here with a variant the rule matches.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "team_ids": [ "string" ], "review_team_ids": [ "string" ], "product_id": "string", "packs": [ "string" ], "rule_variants": { "key": "string" }, "rule_ids": [ "string" ], "excluded_rules": [ { "rule_id": "string", "reason": "string", "excluded_by": "string", "excluded_at": "2026-01-01T00:00:00Z" } ], "llm": { "connection_id": "string", "model": "string" }, "review_drafts": true, "code_suggestions": true}| Field | Type | Required | Description |
|---|---|---|---|
team_ids | string[] | yes | Owning teams: the repository’s and its product’s. Rule scopes match on these |
review_team_ids | string[] | yes | Teams the next review goes to: the owning teams, else the org’s default review team; empty for an org-wide review |
product_id | string | null | yes | |
packs | string[] | yes | Packs that may run: the org’s enabled packs minus this repository’s |
rule_variants | object | yes | The variant each of those packs uses here |
rule_ids | string[] | yes | Custom rules that apply here, after scope and exclusions |
excluded_rules | RuleExclusion[] | yes | |
llm | RepositoryLlm | null | yes | The connection and model the next review uses: the repository’s when it still works, else the integration’s; null when no integration is connected |
review_drafts | boolean | yes | Whether a draft pull request is reviewed before it is marked ready |
code_suggestions | boolean | yes | Whether the next review posts code suggestions |
404— The repository list does not have it
POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/suggestions/{pack_name}/apply
Section titled “POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/suggestions/{pack_name}/apply”Use the suggested rule variant for this pack
Sets rule_variants[pack_name] to the suggestion and clears the suggestion.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
pack_name | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "provider": "github", "external_id": "string", "full_name": "string", "status": "active", "source": "sync", "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "excluded_rules": [ { "rule_id": "string", "reason": "string", "excluded_by": "string", "excluded_at": "2026-01-01T00:00:00Z" } ], "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ "string" ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true, "filled_by": { "team_ids": "string", "product_id": "string", "enabled_packs": "string", "knowledge": "string", "review_drafts": "string", "rule_variants": { "key": "string" } }, "knowledge_sync": { "state": "running", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "commit_sha": "string", "files": 0, "proposals": 0, "truncated": false, "error": "string" }, "scan": { "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "slices_left": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z" }, "suggested_packs": [ "string" ], "suggested_rule_variants": { "key": "string" }, "first_seen_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_pull_request_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | The host’s id for the repository — GitHub repository id, GitLab project id |
full_name | string | yes | As a person writes it: acme/infra, acme/platform/infra |
status | "active" | "removed" | no | |
source | "sync" | "webhook" | yes | |
team_ids | string[] | no | Owning teams. Empty until someone assigns one. |
product_id | string | null | no | The product it belongs to, if any (models/catalog.py) |
enabled_packs | string[] | null | no | Packs that run here on top of the org’s and the product’s. Null until someone sets it. |
rule_variants | object | no | Pack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”} |
excluded_rules | RuleExclusion[] | no | Custom rules turned off here, each with the reason |
llm | RepositoryLlm | null | no | Null: the integration’s connection and model |
knowledge | RepositoryKnowledge | null | no | Files rules are drawn from, such as ADRs. Null: none are read. |
review_drafts | boolean | null | no | Whether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false. |
code_suggestions | boolean | null | no | Post code suggestions on this repository’s pull requests. Null: the org’s setting. |
filled_by | FilledBy | no | The ownership rule pattern that filled each setting of a repository (services/repositories/ownership.py). A setting not listed was set by a person, or never set. |
knowledge_sync | KnowledgeSyncState | null | no | The last sync of those files |
scan | ScanState | null | no | The last scan of the default branch. Null: never scanned. |
suggested_packs | string[] | no | Packs that claim files here but are not enabled for it, from a survey of its file tree or a review’s skipped files. Never enabled on their own: apply or dismiss each. |
suggested_rule_variants | object | no | Pack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it. |
first_seen_at | string (date-time) | yes | |
updated_at | string (date-time) | yes | |
last_pull_request_at | string (date-time) | null | no | When a pull or merge request on this repository last asked for a review |
404— Not Found
POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/suggestions/{pack_name}/dismiss
Section titled “POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/suggestions/{pack_name}/dismiss”Dismiss the suggested rule variant for this pack
Clears the suggestion. The same variant is not suggested again for this pack; a different one can be.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
pack_name | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "provider": "github", "external_id": "string", "full_name": "string", "status": "active", "source": "sync", "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "excluded_rules": [ { "rule_id": "string", "reason": "string", "excluded_by": "string", "excluded_at": "2026-01-01T00:00:00Z" } ], "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ "string" ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true, "filled_by": { "team_ids": "string", "product_id": "string", "enabled_packs": "string", "knowledge": "string", "review_drafts": "string", "rule_variants": { "key": "string" } }, "knowledge_sync": { "state": "running", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "commit_sha": "string", "files": 0, "proposals": 0, "truncated": false, "error": "string" }, "scan": { "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "slices_left": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z" }, "suggested_packs": [ "string" ], "suggested_rule_variants": { "key": "string" }, "first_seen_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_pull_request_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | The host’s id for the repository — GitHub repository id, GitLab project id |
full_name | string | yes | As a person writes it: acme/infra, acme/platform/infra |
status | "active" | "removed" | no | |
source | "sync" | "webhook" | yes | |
team_ids | string[] | no | Owning teams. Empty until someone assigns one. |
product_id | string | null | no | The product it belongs to, if any (models/catalog.py) |
enabled_packs | string[] | null | no | Packs that run here on top of the org’s and the product’s. Null until someone sets it. |
rule_variants | object | no | Pack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”} |
excluded_rules | RuleExclusion[] | no | Custom rules turned off here, each with the reason |
llm | RepositoryLlm | null | no | Null: the integration’s connection and model |
knowledge | RepositoryKnowledge | null | no | Files rules are drawn from, such as ADRs. Null: none are read. |
review_drafts | boolean | null | no | Whether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false. |
code_suggestions | boolean | null | no | Post code suggestions on this repository’s pull requests. Null: the org’s setting. |
filled_by | FilledBy | no | The ownership rule pattern that filled each setting of a repository (services/repositories/ownership.py). A setting not listed was set by a person, or never set. |
knowledge_sync | KnowledgeSyncState | null | no | The last sync of those files |
scan | ScanState | null | no | The last scan of the default branch. Null: never scanned. |
suggested_packs | string[] | no | Packs that claim files here but are not enabled for it, from a survey of its file tree or a review’s skipped files. Never enabled on their own: apply or dismiss each. |
suggested_rule_variants | object | no | Pack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it. |
first_seen_at | string (date-time) | yes | |
updated_at | string (date-time) | yes | |
last_pull_request_at | string (date-time) | null | no | When a pull or merge request on this repository last asked for a review |
404— Not Found
POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/pack-suggestions/{pack_name}/apply
Section titled “POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/pack-suggestions/{pack_name}/apply”Enable a suggested pack on this repository
Adds the pack to the repository’s enabled_packs and clears the suggestion.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
pack_name | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "provider": "github", "external_id": "string", "full_name": "string", "status": "active", "source": "sync", "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "excluded_rules": [ { "rule_id": "string", "reason": "string", "excluded_by": "string", "excluded_at": "2026-01-01T00:00:00Z" } ], "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ "string" ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true, "filled_by": { "team_ids": "string", "product_id": "string", "enabled_packs": "string", "knowledge": "string", "review_drafts": "string", "rule_variants": { "key": "string" } }, "knowledge_sync": { "state": "running", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "commit_sha": "string", "files": 0, "proposals": 0, "truncated": false, "error": "string" }, "scan": { "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "slices_left": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z" }, "suggested_packs": [ "string" ], "suggested_rule_variants": { "key": "string" }, "first_seen_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_pull_request_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | The host’s id for the repository — GitHub repository id, GitLab project id |
full_name | string | yes | As a person writes it: acme/infra, acme/platform/infra |
status | "active" | "removed" | no | |
source | "sync" | "webhook" | yes | |
team_ids | string[] | no | Owning teams. Empty until someone assigns one. |
product_id | string | null | no | The product it belongs to, if any (models/catalog.py) |
enabled_packs | string[] | null | no | Packs that run here on top of the org’s and the product’s. Null until someone sets it. |
rule_variants | object | no | Pack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”} |
excluded_rules | RuleExclusion[] | no | Custom rules turned off here, each with the reason |
llm | RepositoryLlm | null | no | Null: the integration’s connection and model |
knowledge | RepositoryKnowledge | null | no | Files rules are drawn from, such as ADRs. Null: none are read. |
review_drafts | boolean | null | no | Whether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false. |
code_suggestions | boolean | null | no | Post code suggestions on this repository’s pull requests. Null: the org’s setting. |
filled_by | FilledBy | no | The ownership rule pattern that filled each setting of a repository (services/repositories/ownership.py). A setting not listed was set by a person, or never set. |
knowledge_sync | KnowledgeSyncState | null | no | The last sync of those files |
scan | ScanState | null | no | The last scan of the default branch. Null: never scanned. |
suggested_packs | string[] | no | Packs that claim files here but are not enabled for it, from a survey of its file tree or a review’s skipped files. Never enabled on their own: apply or dismiss each. |
suggested_rule_variants | object | no | Pack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it. |
first_seen_at | string (date-time) | yes | |
updated_at | string (date-time) | yes | |
last_pull_request_at | string (date-time) | null | no | When a pull or merge request on this repository last asked for a review |
404— No suggestion for this pack
POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/pack-suggestions/{pack_name}/dismiss
Section titled “POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/pack-suggestions/{pack_name}/dismiss”Dismiss a suggested pack on this repository
Clears the suggestion. The pack is never suggested on this repository again; it can still be enabled by hand.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
pack_name | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "provider": "github", "external_id": "string", "full_name": "string", "status": "active", "source": "sync", "team_ids": [ "string" ], "product_id": "string", "enabled_packs": [ "string" ], "rule_variants": { "key": "string" }, "excluded_rules": [ { "rule_id": "string", "reason": "string", "excluded_by": "string", "excluded_at": "2026-01-01T00:00:00Z" } ], "llm": { "connection_id": "string", "model": "string" }, "knowledge": { "sources": [ { "kind": "adr", "paths": [ "string" ], "applies_to": "repository" } ] }, "review_drafts": true, "code_suggestions": true, "filled_by": { "team_ids": "string", "product_id": "string", "enabled_packs": "string", "knowledge": "string", "review_drafts": "string", "rule_variants": { "key": "string" } }, "knowledge_sync": { "state": "running", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z", "commit_sha": "string", "files": 0, "proposals": 0, "truncated": false, "error": "string" }, "scan": { "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "slices_left": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z" }, "suggested_packs": [ "string" ], "suggested_rule_variants": { "key": "string" }, "first_seen_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_pull_request_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | The host’s id for the repository — GitHub repository id, GitLab project id |
full_name | string | yes | As a person writes it: acme/infra, acme/platform/infra |
status | "active" | "removed" | no | |
source | "sync" | "webhook" | yes | |
team_ids | string[] | no | Owning teams. Empty until someone assigns one. |
product_id | string | null | no | The product it belongs to, if any (models/catalog.py) |
enabled_packs | string[] | null | no | Packs that run here on top of the org’s and the product’s. Null until someone sets it. |
rule_variants | object | no | Pack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”} |
excluded_rules | RuleExclusion[] | no | Custom rules turned off here, each with the reason |
llm | RepositoryLlm | null | no | Null: the integration’s connection and model |
knowledge | RepositoryKnowledge | null | no | Files rules are drawn from, such as ADRs. Null: none are read. |
review_drafts | boolean | null | no | Whether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false. |
code_suggestions | boolean | null | no | Post code suggestions on this repository’s pull requests. Null: the org’s setting. |
filled_by | FilledBy | no | The ownership rule pattern that filled each setting of a repository (services/repositories/ownership.py). A setting not listed was set by a person, or never set. |
knowledge_sync | KnowledgeSyncState | null | no | The last sync of those files |
scan | ScanState | null | no | The last scan of the default branch. Null: never scanned. |
suggested_packs | string[] | no | Packs that claim files here but are not enabled for it, from a survey of its file tree or a review’s skipped files. Never enabled on their own: apply or dismiss each. |
suggested_rule_variants | object | no | Pack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it. |
first_seen_at | string (date-time) | yes | |
updated_at | string (date-time) | yes | |
last_pull_request_at | string (date-time) | null | no | When a pull or merge request on this repository last asked for a review |
404— No suggestion for this pack
GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/knowledge
Section titled “GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/knowledge”List the files the repository’s knowledge sources read
One entry per file, as of the last sync that read it: its status, what the sync did with it, and how many rule proposals it produced.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "documents": [ { "org_id": "string", "provider": "string", "external_id": "string", "kind": "adr", "path": "string", "blob_sha": "string", "commit_sha": "string", "title": "string", "number": "string", "status": "proposed", "outcome": "extracted", "detail": "string", "proposals": 0, "injection_scored": false, "context": [ "string" ], "skipped": [ "string" ], "read_at": "2026-01-01T00:00:00Z" } ]}404— Not Found
POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/knowledge/sync
Section titled “POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/knowledge/sync”Read the repository’s knowledge sources now
Reads the repository’s knowledge sources (its ADRs) now in the background: {"started": true}, or false when a sync is already running. The sync reads the default branch’s head and skips files unchanged since the last sync. Its outcome appears on the repository as knowledge_sync, GET .../knowledge lists the files read, and its proposals appear under /rule-proposals.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
org_id | string | yes |
Response 202 (application/json)
{ "started": true}| Field | Type | Required | Description |
|---|---|---|---|
started | boolean | yes | False when a sync of this repository is already running |
404— Not Found409— The repository has no knowledge sources
POST /v1/admin/knowledge/sync
Section titled “POST /v1/admin/knowledge/sync”Sync every repository whose knowledge sources are due
Platform-admin only. Starts a background sync for each repository whose last one finished more than knowledge.sync_interval_hours ago, or never ran. Safe for OpenTremor-task-scheduler to call on a short heartbeat: a repository synced recently, or syncing now, is skipped.
Response 200 (application/json)
{ "started": 0}| Field | Type | Required | Description |
|---|---|---|---|
started | integer | yes | Repositories whose sync was started |
POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/scan/preview
Section titled “POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/scan/preview”Preview a scan of the repository’s existing code
Reads the default branch’s file list, never file content, and makes no LLM call. Returns, per pack, the files it would read and an estimate of the units, plus files no pack reads, files skipped as vendored, generated or over 200 KB, and test files. A plan reads test files only with include_tests. The generic pack never takes part in a scan.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "branch": "string", "commit_sha": "string", "packs": [ { "pack": "string", "files": 0, "bytes": 0, "estimated_units": 0, "rules_by_category": { "key": 0 } } ], "unmatched_by_extension": { "key": 0 }, "suggested_packs": [ "string" ], "excluded": 0, "tests": 0, "truncated": true, "remaining_budget_usd": 0}| Field | Type | Required | Description |
|---|---|---|---|
branch | string | yes | |
commit_sha | string | yes | |
packs | PackEstimate[] | yes | Every pack that would read at least one file, with the most files first |
unmatched_by_extension | object | yes | Files no pack reads, grouped by extension |
suggested_packs | string[] | no | Packs that claim files here but are not enabled for this repository. Stored on the repository as suggestions; enable one to scan with it. |
excluded | integer | yes | Files skipped as vendored, generated or oversized |
tests | integer | yes | Test files, excluded from the counts above. A plan reads them with include_tests. |
truncated | boolean | yes | The host listed only part of the tree |
remaining_budget_usd | number | null | yes | What remains of this month’s LLM budget. Null means no cap. |
404— Not Found409— No integration is connected502— The code host failed
GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/scan
Section titled “GET /v1/orgs/{org_id}/repositories/{provider}/{external_id}/scan”Get the repository’s last scan
Its status, the slices it ran and those left for a resume, and the job that runs it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "slices_left": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | |
revision_id | string | yes | |
commit_sha | string | yes | |
job_id | string | yes | |
status | "queued" | "running" | "done" | "stopped" | "failed" | yes | |
plan | ScanPlan | yes | What this run was asked to do |
slices_done | ScanSlice[] | no | |
slices_left | ScanSlice[] | no | What a resume runs |
units | integer | no | Units this run ingested |
analysed_units | integer | no | Units this run analysed |
reused_units | integer | no | Units already analysed before this run, whose analysis it reused without an LLM call |
stopped_reason | string | null | no | |
started_at | string (date-time) | yes | |
finished_at | string (date-time) | null | no |
404— Unknown repository, or never scanned
POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/scan
Section titled “POST /v1/orgs/{org_id}/repositories/{provider}/{external_id}/scan”Start or resume a scan of the repository’s existing code
With a plan, scans the default branch’s head: each slice runs in order, with a pack and optionally folders. A run stops before a slice that would exceed max_units, when the monthly LLM budget is spent, or when a slice reads more than 5,000 files. Without a plan, resumes the slices the last run left, at the commit it read.
Findings go to the repository’s own changeset, scan-{provider}-{external_id}, and never hold a pull request. Code already analysed by an earlier scan or a pull request keeps its analysis with no new LLM call; the scan reports those units as reused_units. A finding is closed only if a run read the code again and no longer reported it. Units count against the plan’s usage, as they do for a pull request.
A slice’s categories limits its pack to its rules in those categories (the preview’s rules_by_category lists them). Each unit is still one LLM call, with a shorter prompt. A run with any such slice closes no finding, and a later full scan or pull request runs every rule on the same code again and is billed again.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | "github" | "gitlab" | yes | |
external_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }}| Field | Type | Required | Description |
|---|---|---|---|
plan | ScanPlan | null | no | The plan to run. Null means resume the slices the last scan left, at its commit. |
Response 202 (application/json)
{ "changeset": "string", "revision_id": "string", "commit_sha": "string", "job_id": "string", "status": "queued", "plan": { "slices": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "max_units": 1, "include_tests": false }, "slices_done": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "slices_left": [ { "pack": "string", "paths": [ "string" ], "categories": [ "string" ] } ], "units": 0, "analysed_units": 0, "reused_units": 0, "stopped_reason": "string", "started_at": "2026-01-01T00:00:00Z", "finished_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | |
revision_id | string | yes | |
commit_sha | string | yes | |
job_id | string | yes | |
status | "queued" | "running" | "done" | "stopped" | "failed" | yes | |
plan | ScanPlan | yes | What this run was asked to do |
slices_done | ScanSlice[] | no | |
slices_left | ScanSlice[] | no | What a resume runs |
units | integer | no | Units this run ingested |
analysed_units | integer | no | Units this run analysed |
reused_units | integer | no | Units already analysed before this run, whose analysis it reused without an LLM call |
stopped_reason | string | null | no | |
started_at | string (date-time) | yes | |
finished_at | string (date-time) | null | no |
404— Not Found409— A scan is already running, or no integration is connected
Products
Section titled “Products”A product is a named group of repositories, such as an API, its web app and its infrastructure. Its teams review every repository in it, in addition to each repository’s own teams, and a custom rule can target it. It grants no access. Reads need products:read (viewer and up); writes need products:manage (admin).
GET /v1/orgs/{org_id}/products
Section titled “GET /v1/orgs/{org_id}/products”List the org’s products
The org’s products, by name. Teams deleted since then are left out of team_ids.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "products": [ { "product_id": "string", "name": "string", "description": "string", "team_ids": [ "string" ], "enabled_packs": [ "string" ], "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ]}POST /v1/orgs/{org_id}/products
Section titled “POST /v1/orgs/{org_id}/products”Create a product
Creates a product. product_id is a slug of name and never changes. Every team ID must be one of the org’s teams. enabled_packs run on every repository of the product, on top of the org’s.
repositories moves those repositories into the new product, out of any product they are in. It needs the repositories:manage permission too. An unknown repository fails the request and creates nothing.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "name": "string", "description": "string", "team_ids": [ "string" ], "repositories": [ { "provider": "github", "external_id": "string" } ], "enabled_packs": [ "string" ]}| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
description | string | null | no | |
team_ids | string[] | no | Owning teams |
repositories | RepositoryKey[] | no | Repositories to move into the product, out of any product they are in. Needs repositories:manage too. |
enabled_packs | string[] | no | Packs that run on every repository of the product, on top of the org’s |
Response 201 (application/json)
{ "product_id": "string", "name": "string", "description": "string", "team_ids": [ "string" ], "enabled_packs": [ "string" ], "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
name | string | yes | |
description | string | null | no | |
team_ids | string[] | yes | Owning teams; teams deleted since are left out |
enabled_packs | string[] | no | Packs that run on every repository of the product, on top of the org’s |
created_by | string | null | no | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | null | no |
403—repositoriesis set without therepositories:managepermission404— An unknown repository
GET /v1/orgs/{org_id}/products/{product_id}
Section titled “GET /v1/orgs/{org_id}/products/{product_id}”Get one product
One product.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "product_id": "string", "name": "string", "description": "string", "team_ids": [ "string" ], "enabled_packs": [ "string" ], "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
name | string | yes | |
description | string | null | no | |
team_ids | string[] | yes | Owning teams; teams deleted since are left out |
enabled_packs | string[] | no | Packs that run on every repository of the product, on top of the org’s |
created_by | string | null | no | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | null | no |
404— Not Found
PATCH /v1/orgs/{org_id}/products/{product_id}
Section titled “PATCH /v1/orgs/{org_id}/products/{product_id}”Change a product
Omitted fields are left alone; description: null clears it. team_ids and enabled_packs replace their lists.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "name": "string", "description": "string", "team_ids": [ "string" ], "enabled_packs": [ "string" ]}| Field | Type | Required | Description |
|---|---|---|---|
name | string | null | no | |
description | string | null | no | |
team_ids | string[] | null | no | |
enabled_packs | string[] | null | no | Replaces the list. Send [] to clear it. |
Response 200 (application/json)
{ "product_id": "string", "name": "string", "description": "string", "team_ids": [ "string" ], "enabled_packs": [ "string" ], "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
name | string | yes | |
description | string | null | no | |
team_ids | string[] | yes | Owning teams; teams deleted since are left out |
enabled_packs | string[] | no | Packs that run on every repository of the product, on top of the org’s |
created_by | string | null | no | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | null | no |
404— Not Found
DELETE /v1/orgs/{org_id}/products/{product_id}
Section titled “DELETE /v1/orgs/{org_id}/products/{product_id}”Delete a product
Its repositories leave the product and keep their own teams, so their reviews still route. Ownership rules lose the product; a rule left with nothing to assign is removed.
A custom rule scoped only to this product runs nowhere afterwards. Its goals and their pull request verdicts are deleted.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Not Found
GET /v1/orgs/{org_id}/products/{product_id}/overview
Section titled “GET /v1/orgs/{org_id}/products/{product_id}/overview”A product’s repositories and open findings
The product’s repositories, including removed ones, each with its open, needs-review and acknowledged findings by severity, its number of changesets and the start date of its newest revision. open_findings totals the product: a finding seen in two of its repositories counts once in the total and once in each repository’s row.
Read through the repositories as they are grouped now: a repository moved to another product takes its findings and changesets with it.
In the dashboard: Products → a product.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "product_id": "string", "name": "string", "repositories": [ { "repository": "string", "full_name": "string", "status": "string", "open_findings": { "key": 0 }, "changesets": 0, "last_revision_at": "2026-01-01T00:00:00Z" } ], "open_findings": { "key": 0 }}| Field | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
name | string | yes | |
repositories | RepositoryActivity[] | yes | |
open_findings | object | yes | By severity over all its repositories, each finding counted once even when it was seen in two of them |
404— Not Found
GET /v1/orgs/{org_id}/products/{product_id}/report
Section titled “GET /v1/orgs/{org_id}/products/{product_id}/report”A product’s open findings as a report
Open, needs-review and acknowledged findings from every repository in the product, with one section per repository and its recent changesets, after the rules with the most findings. include_suppressed=true lists suppressed and false-positive findings too.
format: markdown (default), html, or json for the data the report renders. The response is the report itself. detail=summary keeps CRITICAL and HIGH findings. theme (light or dark) sets the HTML report’s theme. Org report templates apply to changeset reports only.
In the dashboard: Products → a product → Report.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
format | ReportOutput | null | no | markdown (default), html or json. The response is the report itself: text/markdown, text/html, or the report data as JSON. |
detail | ReportDetail | no | summary keeps CRITICAL and HIGH findings only. On a changeset report in Markdown, it also uses the short pull request comment layout. |
include_suppressed | boolean | no | Also list findings triaged as suppressed or false positive |
theme | "light" | "dark" | null | no | HTML report theme: light or dark. Follows the reader’s system setting when omitted. |
Response 200 (application/json)
{ "timestamp": "string", "kind": "product", "title": "string", "include_suppressed": true, "totals": { "key": 0 }, "finding_count": 0, "repositories": [ {} ], "top_rules": [ {} ]}| Field | Type | Required | Description |
|---|---|---|---|
timestamp | string | yes | |
kind | "product" | "repository" | yes | |
title | string | yes | |
include_suppressed | boolean | yes | |
totals | object | yes | Findings by severity, worst first |
finding_count | integer | yes | |
repositories | object[] | yes | One section per repository: its activity, findings and recent changesets |
top_rules | object[] | yes | The rules with the most findings |
404— Not Found
Product goals
Section titled “Product goals”A product’s goals: where it is heading, as ordered steps. Each reviewed pull request on the product’s repositories is checked against its active goals by one LLM call, and the verdict appears in the pull request comment. A verdict never changes a step: a person does, or a step’s measure when its rules have no open finding left. Reads need products:read (viewer and up); writes need goals:manage (admin).
GET /v1/orgs/{org_id}/products/{product_id}/goals
Section titled “GET /v1/orgs/{org_id}/products/{product_id}/goals”List a product’s goals
The product’s goals, oldest first, with their steps in order. A step with a measure carries open_findings: the open, needs-review and acknowledged findings its rules still have in the product’s repositories.
In the dashboard: Products → a product → Goals.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "goals": [ { "goal_id": "string", "product_id": "string", "title": "string", "description": "string", "status": "draft", "target_date": "2026-01-01", "paths": [ "string" ], "jira_key": "string", "jira_url": "string", "steps": [ { "step_id": "string", "title": "string", "description": "string", "status": "todo", "measure": { "rule_ids": [ null ], "min_severity": "LOW" }, "guard": false, "jira_key": "string", "jira_url": "string", "open_findings": 0, "done_at": "2026-01-01T00:00:00Z", "done_by": "string" } ], "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ]}404— Not Found
POST /v1/orgs/{org_id}/products/{product_id}/goals
Section titled “POST /v1/orgs/{org_id}/products/{product_id}/goals”Create a goal
Creates a goal with its steps. A goal starts as draft unless status says otherwise; only active goals are checked on pull requests. Every step starts as todo.
paths limits the goal to pull requests that change a matching file (* matches across /). A step’s measure makes it countable: it is marked done when no open finding from its rules remains in the product. guard holds a pull request that regresses the step once it is done.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "title": "string", "description": "string", "status": "draft", "target_date": "2026-01-01", "paths": [ "string" ], "jira_key": "string", "steps": [ { "step_id": "string", "title": "string", "description": "string", "measure": { "rule_ids": [ "string" ], "min_severity": "LOW" }, "guard": false, "jira_key": "string" } ]}| Field | Type | Required | Description |
|---|---|---|---|
title | string | yes | |
description | string | null | no | What “done” looks like |
status | "draft" | "active" | "achieved" | "abandoned" | no | |
target_date | string (date) | null | no | |
paths | string[] | no | Globs of the files that can matter. A pull request that changes none of them is not checked against this goal. Empty: every pull request is. |
jira_key | string | null | no | The goal’s Jira epic |
steps | StepInput[] | no |
Response 201 (application/json)
{ "goal_id": "string", "product_id": "string", "title": "string", "description": "string", "status": "draft", "target_date": "2026-01-01", "paths": [ "string" ], "jira_key": "string", "jira_url": "string", "steps": [ { "step_id": "string", "title": "string", "description": "string", "status": "todo", "measure": { "rule_ids": [ "string" ], "min_severity": "LOW" }, "guard": false, "jira_key": "string", "jira_url": "string", "open_findings": 0, "done_at": "2026-01-01T00:00:00Z", "done_by": "string" } ], "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}404— Not Found
GET /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}
Section titled “GET /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}”Get one goal
One goal, with its steps and their measures.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
goal_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "goal_id": "string", "product_id": "string", "title": "string", "description": "string", "status": "draft", "target_date": "2026-01-01", "paths": [ "string" ], "jira_key": "string", "jira_url": "string", "steps": [ { "step_id": "string", "title": "string", "description": "string", "status": "todo", "measure": { "rule_ids": [ "string" ], "min_severity": "LOW" }, "guard": false, "jira_key": "string", "jira_url": "string", "open_findings": 0, "done_at": "2026-01-01T00:00:00Z", "done_by": "string" } ], "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}404— Not Found
PATCH /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}
Section titled “PATCH /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}”Change a goal
Omitted fields are left alone; description, target_date and jira_key can be set to null. steps replaces the list: name an existing step by its step_id to keep its status, leave the step_id out for a new step. A step left out is deleted. Step statuses change through PATCH …/steps/{step_id}.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
goal_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "title": "string", "description": "string", "status": "draft", "target_date": "2026-01-01", "paths": [ "string" ], "jira_key": "string", "steps": [ { "step_id": "string", "title": "string", "description": "string", "measure": { "rule_ids": [ "string" ], "min_severity": "LOW" }, "guard": false, "jira_key": "string" } ]}Response 200 (application/json)
{ "goal_id": "string", "product_id": "string", "title": "string", "description": "string", "status": "draft", "target_date": "2026-01-01", "paths": [ "string" ], "jira_key": "string", "jira_url": "string", "steps": [ { "step_id": "string", "title": "string", "description": "string", "status": "todo", "measure": { "rule_ids": [ "string" ], "min_severity": "LOW" }, "guard": false, "jira_key": "string", "jira_url": "string", "open_findings": 0, "done_at": "2026-01-01T00:00:00Z", "done_by": "string" } ], "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}404— Not Found
DELETE /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}
Section titled “DELETE /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}”Delete a goal
Deletes the goal and its pull request verdicts. Guard findings it raised stay and are triaged like any finding.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
goal_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Not Found
PATCH /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}/steps/{step_id}
Section titled “PATCH /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}/steps/{step_id}”Set a step’s status
todo, in_progress, done or skipped. Only a person or a measure reaching zero changes a step’s status: a pull request’s verdict never does. A step linked to Jira moves its issue to Done on the next Jira sync once it is done.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
goal_id | string | yes | |
step_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "status": "todo"}Response 200 (application/json)
{ "goal_id": "string", "product_id": "string", "title": "string", "description": "string", "status": "draft", "target_date": "2026-01-01", "paths": [ "string" ], "jira_key": "string", "jira_url": "string", "steps": [ { "step_id": "string", "title": "string", "description": "string", "status": "todo", "measure": { "rule_ids": [ "string" ], "min_severity": "LOW" }, "guard": false, "jira_key": "string", "jira_url": "string", "open_findings": 0, "done_at": "2026-01-01T00:00:00Z", "done_by": "string" } ], "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}404— Not Found
GET /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}/events
Section titled “GET /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}/events”List a goal’s pull request verdicts
Newest first: each pull request push that advanced or regressed the goal, the step it touched, the model’s one-sentence reason and the files it cited. Pushes the model found neutral are not recorded. A verdict is the model’s opinion of untrusted content: it never changes a step’s status.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
goal_id | string | yes | |
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | no |
Response 200 (application/json)
{ "events": [ { "goal_id": "string", "step_id": "string", "verdict": "advances", "reason": "string", "files": [ "string" ], "changeset": "string", "revision_id": "string", "repository": "string", "pull_request": {}, "created_at": "2026-01-01T00:00:00Z" } ]}404— Not Found
POST /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}/jira
Section titled “POST /v1/orgs/{org_id}/products/{product_id}/goals/{goal_id}/jira”Create the goal’s Jira epic and step issues
Creates an epic for the goal and one issue per step, in the product’s Jira target, else the default target. A goal or step that already has a jira_key keeps it. On Jira Cloud each issue’s parent is the epic; on Data Center the issue names the epic in its text.
From then on the Jira sync comments on a step’s issue for each pull request that advances or regresses it, and moves the issue to Done when the step is done. Nothing read from Jira changes the goal.
A Jira error comes back as 502. Issues created before it keep their keys.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
product_id | string | yes | |
goal_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "goal_id": "string", "product_id": "string", "title": "string", "description": "string", "status": "draft", "target_date": "2026-01-01", "paths": [ "string" ], "jira_key": "string", "jira_url": "string", "steps": [ { "step_id": "string", "title": "string", "description": "string", "status": "todo", "measure": { "rule_ids": [ "string" ], "min_severity": "LOW" }, "guard": false, "jira_key": "string", "jira_url": "string", "open_findings": 0, "done_at": "2026-01-01T00:00:00Z", "done_by": "string" } ], "created_by": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}400— Bad Request403— Forbidden404— Not Found409— Conflict502— Bad Gateway
GET /v1/orgs/{org_id}/goal-settings
Section titled “GET /v1/orgs/{org_id}/goal-settings”Get the goal-check model
The LLM connection and model the goal check uses. Both null: the review’s own.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "connection_id": "string", "model": "string"}| Field | Type | Required | Description |
|---|---|---|---|
connection_id | string | null | no | The LLM connection the goal pass uses. Null: the connection of the review it runs in. |
model | string | null | no | The model the goal pass uses, on connection_id. Set both or neither. |
PUT /v1/orgs/{org_id}/goal-settings
Section titled “PUT /v1/orgs/{org_id}/goal-settings”Set the goal-check model
The goal check makes one LLM call per reviewed pull request on a product with active goals. It counts against the monthly LLM budget. With connection_id and model null, it uses the review’s connection and model.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "connection_id": "string", "model": "string"}| Field | Type | Required | Description |
|---|---|---|---|
connection_id | string | null | no | The LLM connection the goal pass uses. Null: the connection of the review it runs in. |
model | string | null | no | The model the goal pass uses, on connection_id. Set both or neither. |
Response 200 (application/json)
{ "connection_id": "string", "model": "string"}| Field | Type | Required | Description |
|---|---|---|---|
connection_id | string | null | no | The LLM connection the goal pass uses. Null: the connection of the review it runs in. |
model | string | null | no | The model the goal pass uses, on connection_id. Set both or neither. |
Notification channels
Section titled “Notification channels”Where an org’s events are delivered. An org holds many channels, each with its own destination (Slack, Teams, email or a signed webhook) and its own event subscription. Every route requires the org’s admin role except the event catalogue, which any member may read.
The destination URL is write-only: for most kinds the URL is the credential, so it is encrypted at rest and never returned; responses carry target_url_hint. A lost URL can only be re-created at the destination.
GET /notifications/slack/callback
Section titled “GET /notifications/slack/callback”Slack OAuth callback
Public, authenticated by its state: Slack redirects the browser here with ?code=&state= once the admin picks a channel. A redirect from a third party carries no session, so the single-use state token minted by the install call identifies the org and admin. It is stored only as a SHA-256 hash and consumed on first use, so a replayed callback creates nothing.
On success a channel is created with provenance: "oauth", a label naming the Slack channel and no event subscriptions: installing must not also mean paging you. The answer is a 307 back to the dashboard with the outcome.
The install asks for incoming-webhook and nothing else. Slack returns a bot access_token anyway and it is discarded, so the integration can only post to the channels that were picked.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
code | string | null | no | |
state | string | null | no | |
error | string | null | no |
200307— Temporary Redirect400— Bad Request
GET /v1/notifications/events
Section titled “GET /v1/notifications/events”Event names a notification channel can subscribe to
The events this deployment’s mounted product can emit: what a channel may subscribe to. Any org member may read it. A platform-only deployment returns an empty list: correct, not degraded, since with no product there is nothing to be notified about.
Response 200 (application/json)
[ { "name": "string", "description": "string", "default_on": true }]GET /v1/orgs/{org_id}/notifications/channels
Section titled “GET /v1/orgs/{org_id}/notifications/channels”List this org’s notification channels
Every channel of this org, oldest first. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
[ { "channel_id": "string", "label": "string", "kind": "slack", "target_url_hint": "string", "recipients": [ { "user_id": "string", "email": "string" } ], "has_secret": true, "events": [ "string" ], "enabled": true, "team_ids": [ "string" ], "slack_mention": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_delivery": { "at": "2026-01-01T00:00:00Z", "ok": true, "status_code": 0, "error": "string" }, "provenance": "manual", "slack": { "team_id": "string", "team_name": "string", "channel": "string", "channel_id": "string", "configuration_url": "string" } }]POST /v1/orgs/{org_id}/notifications/channels
Section titled “POST /v1/orgs/{org_id}/notifications/channels”Create a notification channel
Creates a channel. Requires the org’s admin role. kind picks the body: slack, teams and webhook take a target_url (and, for webhook, an optional signing secret); email takes recipients. A field the kind does not have is a 422.
target_url is checked against notifications.egress at save time; the 422 names the address rule that refused it and the setting an operator would change. It is write-only: for most kinds the URL is the credential, so it is encrypted at rest and never returned. Responses carry target_url_hint (host and first path segment) instead, and a lost URL can only be re-created at the destination.
An email channel’s response lists its recipients with their current addresses. The list is resolved on every read, so a member who left the org no longer appears and is no longer mailed. On a team-scoped channel, team_ids leaves out teams deleted since; an empty list means every team it served was deleted, and the channel receives nothing rather than going org-wide.
In the dashboard: Organization → Connections → Notifications, one tab per channel kind.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "label": "string", "events": [ "string" ], "enabled": true, "team_ids": [ "string" ], "kind": "slack", "target_url": "https://example.com", "secret": "string", "slack_mention": "string"}| Field | Type | Required | Description |
|---|---|---|---|
label | string | yes | How this channel is named in the dashboard — e.g. ‘Security — #sec-alerts’. Free text; the URL it points at is never shown in full, so this is the only thing telling two channels apart. |
events | string[] | no | Event names this channel receives. Validated against the registered catalogue (GET /notifications/events). Unknown names are refused rather than stored, where they would silently match nothing. An empty list means the channel is configured but deliberately silent. |
enabled | boolean | no | |
team_ids | string[] | null | no | The teams this channel serves. It receives an event only when one of the event’s teams is listed, and never an event with no team. Null makes it org-wide: every subscribed event, whatever its teams. Every id must be one of this organization’s teams. |
kind | "slack" | "teams" | "webhook" | yes | Which renderer formats the payload for this destination |
target_url | string (uri) | yes | Where deliveries are POSTed. For kind=‘slack’, a Slack Incoming Webhook URL; for kind=‘teams’, a Teams Workflows webhook URL. Write-only — never returned by any endpoint, because for most kinds the URL is itself the credential. |
secret | string | null | no | kind=‘webhook’ only. Signs the body with HMAC-SHA256 as X-Signature-256: sha256= |
slack_mention | string | null | no | kind=‘slack’ only. A Slack user-group id (S0123ABC) mentioned at the top of every message, so the people in it are notified, not only the channel. |
Response 201 (application/json)
{ "channel_id": "string", "label": "string", "kind": "slack", "target_url_hint": "string", "recipients": [ { "user_id": "string", "email": "string" } ], "has_secret": true, "events": [ "string" ], "enabled": true, "team_ids": [ "string" ], "slack_mention": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_delivery": { "at": "2026-01-01T00:00:00Z", "ok": true, "status_code": 0, "error": "string" }, "provenance": "manual", "slack": { "team_id": "string", "team_name": "string", "channel": "string", "channel_id": "string", "configuration_url": "string" }}| Field | Type | Required | Description |
|---|---|---|---|
channel_id | string | yes | |
label | string | yes | |
kind | "slack" | "teams" | "webhook" | "email" | yes | |
target_url_hint | string | null | no | Host and first path segment only — the full URL is never returned. Null for kind=‘email’. |
recipients | ChannelRecipient[] | null | no | kind=‘email’ only. The active members among the stored recipients. Members who leave the organization are omitted and are not mailed. |
has_secret | boolean | yes | |
events | string[] | yes | |
enabled | boolean | yes | |
team_ids | string[] | null | no | Null: org-wide. A list: the teams this channel serves, deleted teams left out — an empty list means every team it served was deleted, and it receives nothing. |
slack_mention | string | null | no | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | null | no | |
last_delivery | DeliveryRecord | null | no | |
provenance | "manual" | "oauth" | no | How this channel was created. ‘manual’ — an admin pasted a URL, which is every channel that predates the install flow and the only path available to a deployment with no public base URL. ‘oauth’ — Slack handed us the URL after the admin picked a channel on Slack’s own screen. |
slack | SlackChannelInfo | null | no |
409— The org already hasnotifications.max_channels_per_orgchannels (20 by default)
GET /v1/orgs/{org_id}/notifications/channels/{channel_id}
Section titled “GET /v1/orgs/{org_id}/notifications/channels/{channel_id}”Get one notification channel
One channel. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
channel_id | string | yes |
Response 200 (application/json)
{ "channel_id": "string", "label": "string", "kind": "slack", "target_url_hint": "string", "recipients": [ { "user_id": "string", "email": "string" } ], "has_secret": true, "events": [ "string" ], "enabled": true, "team_ids": [ "string" ], "slack_mention": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_delivery": { "at": "2026-01-01T00:00:00Z", "ok": true, "status_code": 0, "error": "string" }, "provenance": "manual", "slack": { "team_id": "string", "team_name": "string", "channel": "string", "channel_id": "string", "configuration_url": "string" }}| Field | Type | Required | Description |
|---|---|---|---|
channel_id | string | yes | |
label | string | yes | |
kind | "slack" | "teams" | "webhook" | "email" | yes | |
target_url_hint | string | null | no | Host and first path segment only — the full URL is never returned. Null for kind=‘email’. |
recipients | ChannelRecipient[] | null | no | kind=‘email’ only. The active members among the stored recipients. Members who leave the organization are omitted and are not mailed. |
has_secret | boolean | yes | |
events | string[] | yes | |
enabled | boolean | yes | |
team_ids | string[] | null | no | Null: org-wide. A list: the teams this channel serves, deleted teams left out — an empty list means every team it served was deleted, and it receives nothing. |
slack_mention | string | null | no | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | null | no | |
last_delivery | DeliveryRecord | null | no | |
provenance | "manual" | "oauth" | no | How this channel was created. ‘manual’ — an admin pasted a URL, which is every channel that predates the install flow and the only path available to a deployment with no public base URL. ‘oauth’ — Slack handed us the URL after the admin picked a channel on Slack’s own screen. |
slack | SlackChannelInfo | null | no |
404— No such channel in this org
PATCH /v1/orgs/{org_id}/notifications/channels/{channel_id}
Section titled “PATCH /v1/orgs/{org_id}/notifications/channels/{channel_id}”Update a notification channel
Partial update: omitted fields keep their value. Requires the org’s admin role.
target_url, secret and recipients keep their stored values when omitted; a recipients value replaces the whole list. "team_ids": null makes the channel org-wide again, and "slack_mention": null stops the mention. To remove a signing secret without setting a new one, pass "clear_secret": true: omitting secret does not clear it, so renaming a channel cannot quietly downgrade its deliveries to unsigned.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
channel_id | string | yes |
Request body (application/json)
{ "label": "string", "target_url": "https://example.com", "secret": "string", "clear_secret": false, "recipients": [ "string" ], "events": [ "string" ], "enabled": true, "team_ids": [ "string" ], "slack_mention": "string"}| Field | Type | Required | Description |
|---|---|---|---|
label | string | null | no | |
target_url | string (uri) | null | no | URL kinds only. |
secret | string | null | no | |
clear_secret | boolean | no | Remove the signing secret. Distinguishes ‘leave it alone’ (omit secret) from ‘send unsigned from now on’. |
recipients | string[] | null | no | kind=‘email’ only. Replaces the whole list. |
events | string[] | null | no | |
enabled | boolean | null | no | |
team_ids | string[] | null | no | The teams this channel serves. It receives an event only when one of the event’s teams is listed, and never an event with no team. Null makes it org-wide: every subscribed event, whatever its teams. Every id must be one of this organization’s teams. Omit to keep the current scope; send null to make the channel org-wide. |
slack_mention | string | null | no | kind=‘slack’ only. Omit to keep; send null to stop mentioning. |
Response 200 (application/json)
{ "channel_id": "string", "label": "string", "kind": "slack", "target_url_hint": "string", "recipients": [ { "user_id": "string", "email": "string" } ], "has_secret": true, "events": [ "string" ], "enabled": true, "team_ids": [ "string" ], "slack_mention": "string", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z", "last_delivery": { "at": "2026-01-01T00:00:00Z", "ok": true, "status_code": 0, "error": "string" }, "provenance": "manual", "slack": { "team_id": "string", "team_name": "string", "channel": "string", "channel_id": "string", "configuration_url": "string" }}| Field | Type | Required | Description |
|---|---|---|---|
channel_id | string | yes | |
label | string | yes | |
kind | "slack" | "teams" | "webhook" | "email" | yes | |
target_url_hint | string | null | no | Host and first path segment only — the full URL is never returned. Null for kind=‘email’. |
recipients | ChannelRecipient[] | null | no | kind=‘email’ only. The active members among the stored recipients. Members who leave the organization are omitted and are not mailed. |
has_secret | boolean | yes | |
events | string[] | yes | |
enabled | boolean | yes | |
team_ids | string[] | null | no | Null: org-wide. A list: the teams this channel serves, deleted teams left out — an empty list means every team it served was deleted, and it receives nothing. |
slack_mention | string | null | no | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | null | no | |
last_delivery | DeliveryRecord | null | no | |
provenance | "manual" | "oauth" | no | How this channel was created. ‘manual’ — an admin pasted a URL, which is every channel that predates the install flow and the only path available to a deployment with no public base URL. ‘oauth’ — Slack handed us the URL after the admin picked a channel on Slack’s own screen. |
slack | SlackChannelInfo | null | no |
404— No such channel in this org
DELETE /v1/orgs/{org_id}/notifications/channels/{channel_id}
Section titled “DELETE /v1/orgs/{org_id}/notifications/channels/{channel_id}”Delete a notification channel
Deletes the channel. Its destination URL cannot be recovered afterwards. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
channel_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— No such channel in this org
POST /v1/orgs/{org_id}/notifications/channels/{channel_id}/test
Section titled “POST /v1/orgs/{org_id}/notifications/channels/{channel_id}/test”Send a test notification to this channel
Delivers a synthetic event and reports what happened. Requires the org’s admin role. This is the one delivery that is not fire-and-forget: its purpose is to answer “does this URL work”. It ignores the channel’s subscriptions and its enabled flag, so a channel can be tested before it is switched on. The result is recorded as the channel’s last_delivery.
status_code is null when nothing was sent: an egress refusal, a DNS failure or a connection error. Check that first: “we refused to call it” and “it answered 404” are different problems.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
channel_id | string | yes |
Response 200 (application/json)
{ "ok": true, "status_code": 0, "error": "string"}404— Not Found
GET /v1/orgs/{org_id}/notifications/slack/manifest
Section titled “GET /v1/orgs/{org_id}/notifications/slack/manifest”A Slack app manifest for this organization
A Slack app manifest for this org. Requires the org’s admin role. Paste manifest into Slack’s Create New App → From a manifest form. The app comes out with incoming-webhook as its only scope, incoming webhooks on, and this deployment’s redirect URL registered: the two settings that otherwise get mistyped.
The guided install uses the org’s own Slack app, so the admin picks a channel on Slack’s consent screen instead of copying a webhook URL. No app of the operator’s is involved. It requires server.public_base_url; without it these routes answer 501, and POST /orgs/{org_id}/notifications/channels is the way in.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "manifest": {}, "target_url": "string", "redirect_url": "string"}| Field | Type | Required | Description |
|---|---|---|---|
manifest | object | yes | Paste into Slack’s Create New App → From a manifest |
target_url | string | yes | Where to paste it — Slack’s app-creation page |
redirect_url | string | yes | The OAuth redirect this deployment will use. Already inside the manifest; surfaced separately so an admin configuring an existing app by hand can copy it without reading JSON. |
501— Not Implemented
GET /v1/orgs/{org_id}/notifications/slack/app
Section titled “GET /v1/orgs/{org_id}/notifications/slack/app”This organization’s stored Slack app
The org’s stored Slack app, without its secret. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "client_id": "string", "has_secret": true, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}404— Not Found
PUT /v1/orgs/{org_id}/notifications/slack/app
Section titled “PUT /v1/orgs/{org_id}/notifications/slack/app”Store this organization’s Slack app credentials
Stores the org’s Slack app client_id and client_secret, from the app’s Basic Information page. Upserts. Requires the org’s admin role. The secret is encrypted at rest and never returned; client_id is public (it travels in the authorize URL) and comes back.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "client_id": "string", "client_secret": "string"}| Field | Type | Required | Description |
|---|---|---|---|
client_id | string | yes | From the Slack app’s Basic Information page. Not a secret — it travels in the authorize URL — so it is returned by GET. |
client_secret | string | yes | From the same page. Encrypted at rest with the key every other org-authored secret uses, and never returned. |
Response 200 (application/json)
{ "client_id": "string", "has_secret": true, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}DELETE /v1/orgs/{org_id}/notifications/slack/app
Section titled “DELETE /v1/orgs/{org_id}/notifications/slack/app”Forget this organization’s Slack app credentials
Forgets the org’s Slack app credentials. Requires the org’s admin role. Channels already installed keep working, since a webhook URL outlives the OAuth grant that produced it; only further installs stop.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Not Found
POST /v1/orgs/{org_id}/notifications/slack/install
Section titled “POST /v1/orgs/{org_id}/notifications/slack/install”Begin a Slack install
Returns the URL to send the admin’s browser to. Requires the org’s admin role. Slack shows its own consent screen with a channel picker; on Allow it redirects back and the channel is created.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "authorize_url": "string", "state": "string"}| Field | Type | Required | Description |
|---|---|---|---|
authorize_url | string | yes | |
state | string | yes | Single-use CSRF token, echoed back by Slack on the callback |
404— No Slack app stored yet501— Not Implemented
Resources and changesets
Section titled “Resources and changesets”Resources are the analysis units ingest stores, keyed by content hash; a changeset groups them, and each ingest into a changeset is a new revision. An analysis belongs to the resource, within the org: the same content analysed once is never sent to the LLM again.
GET /v1/resource/{hash_resource}
Section titled “GET /v1/resource/{hash_resource}”Get a stored resource by hash
Returns the full resource document: hash, value (terraform content), and analysis (null until submitted).
Use the optional filter query parameter to return only one top-level field (e.g. ?filter=value or ?filter=analysis).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
hash_resource | string | yes | Resource content hash |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
filter | string | null | no | Return only this top-level field (value, analysis, hash) |
Response 200 (application/json)
{ "hash": "a3f1c2d4e5b6", "value": { "type": "aws_db_instance", "name": "orders", "action": "create", "body": "…" }}400— Bad Request404— Not Found
POST /v1/{changeset}/analyses
Section titled “POST /v1/{changeset}/analyses”Submit the analyses of claimed units
Stores the analysis of each unit in analyses, and answers one result per unit, in request order. The answer is 200 whatever each unit’s status:
stored— kept.adjustmentslists what the server changed: a quote the unit body does not contain is dropped, and a finding left with none is lowered toLOWconfidencerejected— not kept.errorsnames the finding and the field: arule_idthat is not in the unit’s ruleset, or a rule reported twice. Fix it and send that unit againnot_in_revision— the revision holds no such unitclaimed_by_other— another caller holds a live claim on the unit; drop it
A unit claimed by the caller, or by no one, is accepted; storing its analysis ends the claim. Analysis is global within the organization: the same unit hash has one analysis whichever changesets list it.
Requires analysis:run. Write each analysis as the contract of the claim answer says. A malformed analysis (a missing field, an unknown severity) fails the whole request with 422, naming the unit and field.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Changeset |
Request body (application/json)
{ "revision_id": "string", "analyses": [ { "unit_hash": "string", "verdict": "string", "findings": [ { "rule_id": "string", "title": "string", "severity": "CRITICAL", "confidence": "HIGH", "consequence": "string", "rationale": "string", "remediation": "string", "quotes": [ "string" ], "tags": [ "string" ] } ] } ]}| Field | Type | Required | Description |
|---|---|---|---|
revision_id | string | null | no | The revision the units belong to; the current one when omitted |
analyses | SubmittedAnalysis[] | yes |
Response 200 (application/json)
{ "results": [ { "unit_hash": "string", "status": "stored", "errors": [ { "finding": 0, "field": "string", "detail": "string" } ], "adjustments": [ { "finding": 0, "field": "string", "detail": "string" } ] } ], "progress": { "total": 0, "analysed": 0, "claimed": 0, "claimable": 0 }}| Field | Type | Required | Description |
|---|---|---|---|
results | SubmissionResult[] | yes | One per submitted analysis, in request order |
progress | LoopProgress | yes |
403— Aviewerkey404— A changeset never ingested, or arevision_idit never had
GET /v1/changesets
Section titled “GET /v1/changesets”List changesets
Returns the changesets of the caller’s organization, newest first. Each includes the date it was first used, its current revision, its revision count, and its open, needs-review and acknowledged findings by severity.
repository is the repository a changeset belongs to (provider/external_id). A pull request review sets it, as does an ingest or analyze call that names a repository. It is set once: naming another repository for the same changeset is refused with 409. product_id is the repository’s current product, so a repository moved to another product takes its changesets with it. pull_request is the number, title and link of the pull request analysed by a code-host review.
Filter by repository or by product_id to list changesets from every repository in the product. A changeset with no repository appears in neither result.
Use this endpoint to populate a changeset picker. Changesets are created implicitly by ingest/analyze calls, so there is no other way to discover them.
Every ingest into a changeset (an ingest or analyze call, a dashboard Analyze submission, or a code-host push) creates a new revision, and the newest is current. Every read (report, dump, claims, the pull request comment and status) uses the current revision unless revision names another. A unit present after an earlier push but absent from the latest one is no longer part of the changeset, so a push that fixes a finding clears it from the report and the gate without triage. A unit unchanged between revisions keeps its analysis and is not sent to the LLM again.
In the dashboard: Analysis → Changesets.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
repository | string | null | no | Only this repository’s changesets (provider/external_id) |
product_id | string | null | no | Only the changesets of this product’s repositories |
Response 200 (application/json)
[ { "changeset": "gh-acme-infra-42", "created_at": "2026-07-15T08:59:40+00:00", "current_revision_id": "9f2c1e7a...", "revision_count": 3, "repository": "github/742118", "product_id": "checkout", "pull_request": { "number": 42, "title": "Encrypt the logs bucket", "url": "https://github.com/acme/infra/pull/42" }, "open_findings": { "HIGH": 1, "MEDIUM": 2 } }]GET /v1/changesets/{changeset}
Section titled “GET /v1/changesets/{changeset}”Get one changeset
One changeset, as shown in a row of GET /changesets: its repository and that repository’s product, the pull request it reviews, and its open findings by severity.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Changeset |
Response 200 (application/json)
{ "changeset": "string", "created_at": "2026-01-01T00:00:00Z", "current_revision_id": "string", "revision_count": 0, "repository": "string", "product_id": "string", "pull_request": { "number": 0, "title": "string", "url": "string" }, "open_findings": { "key": 0 }}| Field | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | |
created_at | string (date-time) | null | yes | When its first revision started |
current_revision_id | string | null | yes | |
revision_count | integer | yes | |
repository | string | null | yes | provider/external_id of the repository it belongs to, set once; null for an API analysis that named none |
product_id | string | null | yes | The repository’s product now; null when it has none |
pull_request | ChangesetPullRequest | null | no | |
open_findings | object | no | Open, needs-review and acknowledged findings by severity |
404— No such changeset
GET /v1/changesets/{changeset}/revisions
Section titled “GET /v1/changesets/{changeset}/revisions”List a changeset’s revisions
Every revision of changeset, newest first: one per ingest or analyze call, or per GitHub push (its id is then the head commit SHA). Reads — report, dump, the claims loop, the PR gate — use the revision marked current unless ?revision= names another.
Once a revision’s analysis completes, its outcome says what it did to the changeset’s open and needs-review findings: how many it opened, closed and left open.
When every unit of a revision is analysed, the revision closes the open and needs-review findings it no longer reports and records its outcome: opened (findings on units it added), closed (findings it closed; one stays open while another changeset’s current revision still holds its unit) and still_open (findings on units carried over). The outcome is written once and never changes, so later triage does not rewrite what a push did; it remains null until the analysis completes.
A revision whose run was cancelled, stopped by the budget or left units unanalysed closes nothing. The same applies if it is no longer current when its run ends; the newer push handles it. A finding already triaged (acknowledged, suppressed, false_positive) is never closed, and a revision that brings a unit back, such as a revert, reopens its closed findings. closed means the latest complete revision no longer reports the issue, not that someone verified the fix.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Changeset |
Response 200 (application/json)
[ { "revision_id": "string", "created_at": "2026-01-01T00:00:00Z", "source": "string", "resource_count": 0, "current": true, "outcome": { "completed_at": "2026-01-01T00:00:00Z", "opened": { "count": 0, "by_severity": { "key": 0 }, "findings": [ { "resource_hash": "string", "rule_id": "string" } ] }, "closed": { "count": 0, "by_severity": { "key": 0 }, "findings": [ { "resource_hash": "string", "rule_id": "string" } ] }, "still_open": { "count": 0, "by_severity": { "key": 0 }, "findings": [ { "resource_hash": "string", "rule_id": "string" } ] } } }]404— Unknown changeset
GET /v1/changesets/{changeset}/revisions/{revision}/changes
Section titled “GET /v1/changesets/{changeset}/revisions/{revision}/changes”The findings a revision opened, closed and left open
The findings behind a revision’s outcome, compared with the revision before it. 404 while the revision’s analysis is incomplete: it has no outcome yet. A finding purged since is left out of its list.
So the list can be shorter than its count in outcome.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Changeset |
revision | string | yes | Revision id |
Response 200 (application/json)
{ "changeset": "string", "revision_id": "string", "previous_revision_id": "string", "opened": [ { "resource_hash": "string", "rule_id": "string", "unit_address": "string", "severity": "string", "title": "string", "status": "open", "first_seen": "2026-01-01T00:00:00Z", "last_seen": "2026-01-01T00:00:00Z", "occurrence_count": 1, "note": "string", "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z", "changesets": [ "string" ], "assigned_team_ids": [ "string" ], "repositories": [ "string" ], "closed_in": { "changeset": "string", "revision_id": "string", "at": "2026-01-01T00:00:00Z", "status_before": "open" }, "reason_code": "false_positive", "ticket": { "key": "string", "url": "string", "synced_status": "open", "synced_changesets": [ "string" ], "closed_by_opentremor": false, "jira_status": "string", "jira_status_category": "string", "created_at": "2026-01-01T00:00:00Z", "last_error": "string" } } ], "closed": [ { "resource_hash": "string", "rule_id": "string", "unit_address": "string", "severity": "string", "title": "string", "status": "open", "first_seen": "2026-01-01T00:00:00Z", "last_seen": "2026-01-01T00:00:00Z", "occurrence_count": 1, "note": "string", "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z", "changesets": [ "string" ], "assigned_team_ids": [ "string" ], "repositories": [ "string" ], "closed_in": { "changeset": "string", "revision_id": "string", "at": "2026-01-01T00:00:00Z", "status_before": "open" }, "reason_code": "false_positive", "ticket": { "key": "string", "url": "string", "synced_status": "open", "synced_changesets": [ "string" ], "closed_by_opentremor": false, "jira_status": "string", "jira_status_category": "string", "created_at": "2026-01-01T00:00:00Z", "last_error": "string" } } ], "still_open": [ { "resource_hash": "string", "rule_id": "string", "unit_address": "string", "severity": "string", "title": "string", "status": "open", "first_seen": "2026-01-01T00:00:00Z", "last_seen": "2026-01-01T00:00:00Z", "occurrence_count": 1, "note": "string", "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z", "changesets": [ "string" ], "assigned_team_ids": [ "string" ], "repositories": [ "string" ], "closed_in": { "changeset": "string", "revision_id": "string", "at": "2026-01-01T00:00:00Z", "status_before": "open" }, "reason_code": "false_positive", "ticket": { "key": "string", "url": "string", "synced_status": "open", "synced_changesets": [ "string" ], "closed_by_opentremor": false, "jira_status": "string", "jira_status_category": "string", "created_at": "2026-01-01T00:00:00Z", "last_error": "string" } } ]}| Field | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | |
revision_id | string | yes | |
previous_revision_id | string | null | yes | The revision this one is compared with |
opened | FindingRecord[] | yes | |
closed | FindingRecord[] | yes | |
still_open | FindingRecord[] | yes |
404— Not Found
POST /v1/{changeset}/claims
Section titled “POST /v1/{changeset}/claims”Claim units to analyse
Claims up to limit units of the revision that have no analysis yet, for the caller, with the rules they must be analysed against.
A claimed unit is handed to no one else for 10 minutes, or until its analysis lands, so several agents can drain one changeset without analysing a unit twice.
The loop: claim, analyse each unit against rulesets[unit.ruleset_id] as contract says, submit with POST /{changeset}/analyses, claim again. The answer always comes with HTTP 200; status says what to do next:
units— analyseunits, submit, claim againwaiting— every remaining unit is claimed; claim again afterretry_after_seconds, or release your own claims first if you lost track of them (DELETE /{changeset}/claims)done— every unit has an analysis; fetchGET /changesets/{changeset}/report
A ruleset is sent once per ruleset_id, with the rule_ids a finding may name: list the ids you already hold in known_rulesets and it is left out. The contract text comes with the first batch; name its contract_id in known_contract to leave it out. The rules follow what the ingest named: its repository and rule variant.
Requires analysis:run. progress is {total, analysed, claimed, claimable}, and retry_after_seconds (with waiting) is at most 30. A unit’s ruleset_id is null when its pack has no rules. While other callers hold the remaining units, the answer is waiting, never done.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Changeset |
Request body (application/json, optional)
{ "limit": 5, "revision_id": "string", "known_rulesets": [ "string" ], "known_contract": "string"}| Field | Type | Required | Description |
|---|---|---|---|
limit | integer | no | Most units to claim |
revision_id | string | null | no | The revision to drain; the current one when omitted |
known_rulesets | string[] | no | ruleset_ids the caller already holds: their text is not sent again |
known_contract | string | null | no | The contract_id the caller already holds: the contract text is not sent again |
Response 200 (application/json)
{ "status": "units", "changeset": "string", "revision_id": "string", "progress": { "total": 0, "analysed": 0, "claimed": 0, "claimable": 0 }, "retry_after_seconds": 0, "rulesets": { "key": { "rule_ids": [ "string" ], "text": "string" } }, "contract_id": "string", "contract": "string", "units": [ { "unit_hash": "string", "ruleset_id": "string", "type": "string", "name": "string", "action": "string", "body": "string", "metadata": {} } ]}| Field | Type | Required | Description |
|---|---|---|---|
status | "units" | "waiting" | "done" | yes | units: analyse and submit units, then claim again. waiting: every remaining unit is claimed; claim again after retry_after_seconds. done: every unit has an analysis; fetch the report |
changeset | string | yes | |
revision_id | string | null | yes | The revision drained; None for a changeset never ingested |
progress | LoopProgress | yes | |
retry_after_seconds | integer | null | no | |
rulesets | object | no | Rulesets by ruleset_id, for the ids in units the request did not list in known_rulesets |
contract_id | string | yes | Id of the contract text, to list in known_contract |
contract | string | null | no | How to write each analysis, in Markdown. Sent with units unless the request named its id in known_contract |
units | ClaimedUnit[] | no |
403— Aviewerkey404— Arevision_idthe changeset never had
DELETE /v1/{changeset}/claims
Section titled “DELETE /v1/{changeset}/claims”Hand your claims back
Releases the claims the caller holds in the revision, so the units are claimable again at once. Name units with hash (repeat it) to release only those. Another caller’s claims are left alone. Call it when you stop before submitting, or when you restart a loop.
Requires analysis:run. Answers {"released": <count>}.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Changeset |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
revision | string | null | no | Revision id; the current revision when omitted |
hash | string[] | null | no | Release only these units; repeat it |
Response 200 (application/json)
{ "released": 0}| Field | Type | Required | Description |
|---|---|---|---|
released | integer | yes | Claims of the caller’s that were handed back |
GET /v1/changesets/{changeset}/dump
Section titled “GET /v1/changesets/{changeset}/dump”List all resources in a changeset
Returns every resource document (including analysis) in one revision of changeset — the current one unless revision names another.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Changeset |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
revision | string | null | no | Revision id; the current revision when omitted |
200
GET /v1/changesets/{changeset}/report
Section titled “GET /v1/changesets/{changeset}/report”A changeset’s report
Renders the report of one revision of changeset — the current one unless revision names another — from its stored analysis. The response is the report itself.
format:markdown(default),html, orjsonfor the data the templates render.detail=summarykeeps CRITICAL and HIGH findings. In Markdown it uses the short pull request comment layout.link=truemints a public, time-limited link to the full HTML report and puts it in the report. The link is built fromserver.dashboard_base_url, orserver.public_base_urlif that is unset, never from the request’sHostorX-Forwarded-*headers. Without either setting there is no link.
The org’s default report template for the format applies when one is set (GET /orgs/{org_id}/report-templates), else the built-in one. template_id renders with one specific template; without format its own format applies, and a different format is a 422.
Each finding carries its triage status: suppressed and false_positive findings are left out unless include_suppressed=true. theme (light or dark) sets an HTML report’s theme.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Changeset |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
format | ReportOutput | null | no | markdown (default), html or json. The response is the report itself: text/markdown, text/html, or the report data as JSON. |
detail | ReportDetail | no | summary keeps CRITICAL and HIGH findings only. On a changeset report in Markdown, it also uses the short pull request comment layout. |
include_suppressed | boolean | no | Also list findings triaged as suppressed or false positive |
theme | "light" | "dark" | null | no | HTML report theme: light or dark. Follows the reader’s system setting when omitted. |
revision | string | null | no | Revision id; the current revision when omitted |
template_id | string | null | no | Render with this org report template instead of the org’s default. Without format, the template’s own format applies; with a different one, 422. |
link | boolean | no | Mint a public, time-limited link to the full HTML report and put it in the report (report_html_url in JSON). No link when the platform has no public address set. |
Response 200 (application/json)
{ "timestamp": "string", "changeset": "string", "revision_id": "string", "pack": "string", "packs": [ "string" ], "resource_count": 0, "resources": [ {} ], "analysed_with": [ { "source": "server", "connection_id": "string", "model": "string" } ], "report_html_url": "string", "dashboard_url": "string", "since_previous": {}, "checked_categories": [ {} ], "repository": {}, "product": {}, "pull_request": {}}| Field | Type | Required | Description |
|---|---|---|---|
timestamp | string | yes | |
changeset | string | yes | |
revision_id | string | null | yes | |
pack | string | yes | packs, joined with commas |
packs | string[] | yes | |
resource_count | integer | yes | |
resources | object[] | yes | Each unit’s pack-specific fields, with hash, analysis (its findings, each with a triage status) and analysed_with |
analysed_with | AnalysedWith[] | yes | |
report_html_url | string | null | yes | Public, time-limited link; set by link=true |
dashboard_url | string | null | yes | |
since_previous | object | null | yes | What this revision opened, closed and left open since the one before it |
checked_categories | object[] | yes | {pack, categories} for each pack the revision limited to some rule categories |
repository | object | null | yes | |
product | object | null | yes | |
pull_request | object | null | yes |
404—template_idnames no template in this org
GET /v1/changesets/{changeset}/gate
Section titled “GET /v1/changesets/{changeset}/gate”Whether a changeset’s findings let its change merge
The answer a pull request’s commit status gives, for a CI job that analysed a diff through the API and needs an exit code: success lets the change through, failure means an open CRITICAL/HIGH finding, pending means a finding waits for a human or some units are not analysed yet. Reads the current revision unless revision names another. Triage in the dashboard changes the answer; asking again picks that up.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Changeset |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
revision | string | null | no | Revision id; the current revision when omitted |
Response 200 (application/json)
{ "changeset": "string", "revision_id": "string", "state": "success", "description": "string", "resource_count": 0, "unanalysed_count": 0}| Field | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | |
revision_id | string | yes | The revision the answer is about |
state | "success" | "failure" | "pending" | yes | success lets the change through. failure: an open CRITICAL/HIGH finding. pending: a finding is waiting for a human, or some units are not analysed yet |
description | string | yes | The one line a commit status would carry |
resource_count | integer | yes | Units in the revision |
unanalysed_count | integer | yes | Units with no analysis yet — the gate is pending while any remain |
404— Unknown changeset, or no such revision
POST /v1/changesets/{changeset}/report-links
Section titled “POST /v1/changesets/{changeset}/report-links”Create a public, time-limited link to a changeset’s full report
Mints a new link to the full HTML report of one revision — the current one unless revision names another. Anyone holding the link can open the report without signing in, until the org’s report_link_ttl_hours runs out (PATCH /orgs/{org_id}/report-link-ttl). Every call mints a new link.
The link opens the dashboard’s report page when server.dashboard_base_url is set, and the API’s own GET /reports/{token} otherwise. It returns 409 when neither server.dashboard_base_url nor server.public_base_url is set: there is no public address to put in a link. A platform admin sets them in PATCH /admin/settings.
Any member who can read the report may call this endpoint. Earlier links stay valid until they expire. A link minted with revision keeps showing that revision after new pushes.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Changeset |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
revision | string | null | no | Revision id; the current revision when omitted |
include_suppressed | boolean | no | Include findings triaged as suppressed/false_positive (hidden by default) |
Response 201 (application/json)
{ "url": "string", "expires_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
url | string | yes | Public URL of the full HTML report |
expires_at | string (date-time) | yes | When the link stops working (the org’s report-link TTL) |
404— Unknown changeset, or arevisionit does not have409— Conflict
Report links
Section titled “Report links”Public report links. POST /changesets/{changeset}/report-links mints one; the dashboard’s share button calls it, and GET /changesets/{changeset}/report?link=true puts one in the report. Nothing else mints a link. A link points to the dashboard’s public report page when server.dashboard_base_url is set, else to the API’s own GET /reports/{token}. Every link is a fresh, high-entropy, time-limited token: do not build or cache the URL yourself.
GET /reports/{token}
Section titled “GET /reports/{token}”Full HTML report — publicly accessible via a time-limited token
Public, no authentication: serves the full HTML report behind a report link, so a link in a report or a pull request comment opens in a browser. The token is the only access control: it is high-entropy, stored only as its SHA-256 hash, and valid for the org’s report_link_ttl_hours (24 by default). Mint one with POST /changesets/{changeset}/report-links. ?theme=light or ?theme=dark pins the theme; without it, the report follows the reader’s system setting.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | yes | Report link token |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
theme | "light" | "dark" | null | no | HTML report theme: light or dark. Follows the viewer’s system setting when omitted. |
200404— Token unknown or expired; both return the same response on purpose
PATCH /v1/orgs/{org_id}/report-link-ttl
Section titled “PATCH /v1/orgs/{org_id}/report-link-ttl”Set how long minted public HTML report links stay valid
Sets how long public report links minted after this call stay valid; links already out keep their expiry. Requires the org’s admin role. Default: 24 hours; range: 1 to 720 (30 days).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "ttl_hours": 1}| Field | Type | Required | Description |
|---|---|---|---|
ttl_hours | integer | yes | 1 hour to 720 hours (30 days) |
Response 200 (application/json)
{ "report_link_ttl_hours": 24}Report templates
Section titled “Report templates”Jinja2 report layouts an org writes instead of the three built-in ones (markdown, markdown_light for the pull request comment and detail=summary, html). A new org gets the built-ins seeded as editable, non-default rows.
A template’s source runs on the server at every render, in Jinja2’s SandboxedEnvironment with no loader, so it cannot include or extends anything. Any rendering error is a 422, never a 500. Because it runs org-written logic, changing templates is admin-only, the same trust boundary as custom rules and LLM connections.
Every template receives a theme variable ("light", "dark" or none). The built-in HTML template uses the dashboard’s colours, loads nothing from the network so a saved report opens offline, and writes the theme as a class on <html>.
Every template also receives analysed_with: one entry per distinct LLM that analysed the report’s units, server connections first. Each entry has source, connection_id and model. A server entry names the LLM connection and its model. A client entry has neither, because the server does not know the model of the caller’s agent. Units analysed before this was recorded have no entry. Each resource also carries its own analysed_with, whose source is scan for a unit only the pattern scan looked at. The built-in HTML template prints the list under the title.
GET /v1/orgs/{org_id}/report-templates
Section titled “GET /v1/orgs/{org_id}/report-templates”List report templates for this org
The org’s report templates; filter by format and is_default. Any member.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
format | ReportFormat | null | no | |
is_default | boolean | null | no |
Response 200 (application/json)
{ "templates": [ { "template_id": "string", "org_id": "string", "name": "string", "format": "markdown", "source": "string", "is_default": false, "is_builtin_seed": false, "created_by": "string", "created_at": "string", "updated_at": "string" } ]}POST /v1/orgs/{org_id}/report-templates
Section titled “POST /v1/orgs/{org_id}/report-templates”Create a custom report template
Requires admin role. template_id is derived from name and is immutable afterwards. format is also immutable — it determines the variables/escaping contract source is written against.
is_default: true makes it the org’s template for its format, used for every report of that format: GET /changesets/{changeset}/report, report links and pull request comments.
In the dashboard: Organization → Features → Report Templates.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "name": "string", "format": "markdown", "source": "string", "is_default": false}| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | |
format | ReportFormat | yes | What a template renders. markdown_light is the short pull request comment layout: CRITICAL and HIGH findings only. The report endpoints ask for it as format=markdown with detail=summary (models/reports.py). |
source | string | yes | Jinja2 template source |
is_default | boolean | no |
Response 201 (application/json)
{ "template_id": "string", "org_id": "string", "name": "string", "format": "markdown", "source": "string", "is_default": false, "is_builtin_seed": false, "created_by": "string", "created_at": "string", "updated_at": "string"}| Field | Type | Required | Description |
|---|---|---|---|
template_id | string | yes | |
org_id | string | yes | |
name | string | yes | |
format | ReportFormat | yes | What a template renders. markdown_light is the short pull request comment layout: CRITICAL and HIGH findings only. The report endpoints ask for it as format=markdown with detail=summary (models/reports.py). |
source | string | yes | |
is_default | boolean | no | |
is_builtin_seed | boolean | no | True for a template imported from the built-in views/templates/*.j2 files at org setup — informational only (dashboard badge). Seeded rows default to is_default=False, same reasoning as custom rules’ seeded-disabled default: existing orgs’ report output shouldn’t change until they explicitly opt in. |
created_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
404— Not Found
GET /v1/orgs/{org_id}/report-templates/{template_id}
Section titled “GET /v1/orgs/{org_id}/report-templates/{template_id}”Get one report template
One report template. Any member.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
template_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "template_id": "string", "org_id": "string", "name": "string", "format": "markdown", "source": "string", "is_default": false, "is_builtin_seed": false, "created_by": "string", "created_at": "string", "updated_at": "string"}| Field | Type | Required | Description |
|---|---|---|---|
template_id | string | yes | |
org_id | string | yes | |
name | string | yes | |
format | ReportFormat | yes | What a template renders. markdown_light is the short pull request comment layout: CRITICAL and HIGH findings only. The report endpoints ask for it as format=markdown with detail=summary (models/reports.py). |
source | string | yes | |
is_default | boolean | no | |
is_builtin_seed | boolean | no | True for a template imported from the built-in views/templates/*.j2 files at org setup — informational only (dashboard badge). Seeded rows default to is_default=False, same reasoning as custom rules’ seeded-disabled default: existing orgs’ report output shouldn’t change until they explicitly opt in. |
created_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
404— Template not found
PATCH /v1/orgs/{org_id}/report-templates/{template_id}
Section titled “PATCH /v1/orgs/{org_id}/report-templates/{template_id}”Update a report template
Requires admin role. Partial update — only fields present in the body change. template_id/format never change. Setting is_default: true unsets any other default this org has for the same format.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
template_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "name": "string", "source": "string", "is_default": true}Response 200 (application/json)
{ "template_id": "string", "org_id": "string", "name": "string", "format": "markdown", "source": "string", "is_default": false, "is_builtin_seed": false, "created_by": "string", "created_at": "string", "updated_at": "string"}| Field | Type | Required | Description |
|---|---|---|---|
template_id | string | yes | |
org_id | string | yes | |
name | string | yes | |
format | ReportFormat | yes | What a template renders. markdown_light is the short pull request comment layout: CRITICAL and HIGH findings only. The report endpoints ask for it as format=markdown with detail=summary (models/reports.py). |
source | string | yes | |
is_default | boolean | no | |
is_builtin_seed | boolean | no | True for a template imported from the built-in views/templates/*.j2 files at org setup — informational only (dashboard badge). Seeded rows default to is_default=False, same reasoning as custom rules’ seeded-disabled default: existing orgs’ report output shouldn’t change until they explicitly opt in. |
created_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
404— Template not found
DELETE /v1/orgs/{org_id}/report-templates/{template_id}
Section titled “DELETE /v1/orgs/{org_id}/report-templates/{template_id}”Delete a report template
Deletes a template. Requires the org’s admin role. If it was the org’s default, reports of that format fall back to the built-in template.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
template_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Template not found
POST /v1/orgs/{org_id}/report-templates/seed-builtin
Section titled “POST /v1/orgs/{org_id}/report-templates/seed-builtin”(Re-)import the built-in templates as editable rows
Requires admin role. Idempotent — skips any template_id already present for this org. Every imported row is created with is_default: false (existing report output shouldn’t change until this org explicitly promotes one).
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "created": 0, "updated": 0, "disabled": 0}| Field | Type | Required | Description |
|---|---|---|---|
created | integer | yes | |
updated | integer | no | Built-in rules whose wording an org never edited, brought in line with the pack file |
disabled | integer | no | Built-in rules an org never edited that left the pack file |
POST /v1/orgs/{org_id}/report-templates/preview
Section titled “POST /v1/orgs/{org_id}/report-templates/preview”Render a draft template source against a changeset or sample data
Renders source (not persisted) against changeset’s analysed resources/findings, using the same data assembly as GET /changesets/{changeset}/report. changeset must already have at least one resource in this org. Without changeset, renders against the demo analysis, built in memory and stored nowhere.
Any member. Every sample finding has the status open.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "source": "string", "format": "markdown", "changeset": "string"}| Field | Type | Required | Description |
|---|---|---|---|
source | string | yes | |
format | ReportFormat | yes | What a template renders. markdown_light is the short pull request comment layout: CRITICAL and HIGH findings only. The report endpoints ask for it as format=markdown with detail=summary (models/reports.py). |
changeset | string | null | no | An existing changeset to render this draft against. Omitted: the demo analysis, built in memory, so a template can be previewed before anything has been analysed. |
Response 200 (application/json)
{ "content": "# prod-deploy-42\n...", "content_type": "text/markdown"}404—changesethas no resources yet409— Nochangeset, and no installed pack ships a demo sample