Skip to content
DashboardWebsite

Endpoints: Integrations, Resources & Reports

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

NameTypeRequiredDescription
codestringyes
statestringyes
  • 200
  • 307 — App created, credentials stored, redirected to the dashboard
  • 400 — Invalid, expired or already used state, or the code exchange with GitHub failed

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 an installation / installation_repositories event acknowledged
  • 401 — Missing or invalid X-Hub-Signature-256 for 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 Hook whose action is open, reopen or update with oldrev (a push; a title edit has none), or an update that takes it out of draft, queues a review. A draft on a repository without review_drafts: true gets a pending commit status and no job (200); leaving draft queues one only on such a repository. The job’s trigger is "scm_webhook", its external_ref is {"provider": "gitlab", "repo": "group/project", "pr_number": <iid>, "head_sha": "…"}, and its changeset is gl-{project_id}-{iid}.
  • A Note Hook for 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

NameTypeRequiredDescription
webhook_idstringyes

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 the code suggestion settings

Whether code suggestions are posted on pull requests, from which severity, and how many per push.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"enabled": false,
"min_severity": "HIGH",
"max_per_review": 10
}
FieldTypeRequiredDescription
enabledbooleannoPost code suggestions on pull requests. A repository can override this setting either way.
min_severity"CRITICAL" | "HIGH" | "MEDIUM"noOnly findings at this severity or above get a suggestion.
max_per_reviewintegernoAt most this many suggestions per push. The rest keep their written next step.

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"enabled": false,
"min_severity": "HIGH",
"max_per_review": 10
}
FieldTypeRequiredDescription
enabledbooleannoPost code suggestions on pull requests. A repository can override this setting either way.
min_severity"CRITICAL" | "HIGH" | "MEDIUM"noOnly findings at this severity or above get a suggestion.
max_per_reviewintegernoAt 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
}
FieldTypeRequiredDescription
enabledbooleannoPost code suggestions on pull requests. A repository can override this setting either way.
min_severity"CRITICAL" | "HIGH" | "MEDIUM"noOnly findings at this severity or above get a suggestion.
max_per_reviewintegernoAt most this many suggestions per push. The rest keep their written next step.

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

NameTypeRequiredDescription
org_idstringyes

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"
}
}
FieldTypeRequiredDescription
installation_idstring | nullnoSet by GitHub’s installation webhook once the App is installed on a repository. Null until then.
llm_backendstringyes
connection_idstringyesThe stored connection webhook runs use
modelstringyes
created_atstring (date-time)yes
github_appGitHubAppInfoyesPublic-safe view of the org’s GitHub App — never the private key or webhook secret.
  • 404 — No App yet

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"connection_id": "string",
"model": "string"
}
FieldTypeRequiredDescription
connection_idstringyesThe 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.
modelstringyesProvider-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"
}
}
FieldTypeRequiredDescription
installation_idstring | nullnoSet by GitHub’s installation webhook once the App is installed on a repository. Null until then.
llm_backendstringyes
connection_idstringyesThe stored connection webhook runs use
modelstringyes
created_atstring (date-time)yes
github_appGitHubAppInfoyesPublic-safe view of the org’s GitHub App — never the private key or webhook secret.
  • 400 — The connection or the model is rejected
  • 404 — 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

NameTypeRequiredDescription
org_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

Query parameters

NameTypeRequiredDescription
namestring | nullno

Response 200 (application/json)

{
"name": "string"
}
FieldTypeRequiredDescription
namestringyesA 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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"connection_id": "string",
"model": "string",
"app_name": "string"
}
FieldTypeRequiredDescription
connection_idstringyesThe 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.
modelstringyesProvider-specific model name
app_namestring | nullnoThe 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"
}
FieldTypeRequiredDescription
manifestobjectyesManifest JSON to POST to GitHub’s App-creation form
statestringyesCSRF state token — round-tripped by GitHub as the state query param
target_urlstringyesWhere to POST the manifest form (github.com’s app-creation page)
  • 400 — Bad Request
  • 409 — Conflict
  • 501 — server.public_base_url is not set: the manifest’s webhook and redirect URLs need a reachable HTTPS address

Get this org’s GitLab integration

The org’s GitLab integration, without webhook_secret. Requires the org’s admin role.

Path parameters

NameTypeRequiredDescription
org_idstringyes

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"
}
FieldTypeRequiredDescription
base_urlstringyes
bot_usernamestringyesThe token’s bot user — the author of our notes
has_tls_cabooleannoWhether the org supplied its own CA bundle
token_expires_atstring | nullnoWhen the access token stops working
webhook_urlstring | nullnoPaste into each project’s Settings → Webhooks. Null until the deployment’s server.public_base_url is set
llm_backendstringyes
connection_idstringyes
modelstringyes
created_atstring (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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"base_url": "string",
"access_token": "string",
"connection_id": "string",
"model": "string",
"tls_ca_pem": "string"
}
FieldTypeRequiredDescription
base_urlstringyesThe GitLab instance’s root URL, e.g. https://gitlab.example.com. Must be allowed by the deployment’s gitlab.egress policy.
access_tokenstringyesA group access token: role Developer, scope api. Write-only — never returned. GitLab requires an expiry date, at most a year out.
connection_idstringyesThe stored LLM connection webhook-triggered analysis calls.
modelstringyesProvider-specific model name
tls_ca_pemstring | nullnoPEM 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"
}
FieldTypeRequiredDescription
base_urlstringyes
bot_usernamestringyesThe token’s bot user — the author of our notes
has_tls_cabooleannoWhether the org supplied its own CA bundle
token_expires_atstring | nullnoWhen the access token stops working
webhook_urlstring | nullnoPaste into each project’s Settings → Webhooks. Null until the deployment’s server.public_base_url is set
llm_backendstringyes
connection_idstringyes
modelstringyes
created_atstring (date-time)yes
webhook_secretstring | nullyesShown 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_pem is 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

NameTypeRequiredDescription
org_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"enabled": true
}
FieldTypeRequiredDescription
enabledbooleanyesWhether 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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"enabled": true,
"connected": true
}
FieldTypeRequiredDescription
enabledbooleanyesWhether a platform admin turned the Jira integration on
connectedbooleanyesWhether this org has a Jira integration that is not paused. With enabled, whether a finding’s issue can be created now.

Get this org’s Jira integration

Path parameters

NameTypeRequiredDescription
org_idstringyes

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"
}
FieldTypeRequiredDescription
base_urlstringyes
flavor"cloud" | "data_center"yes
emailstring | nullyes
account_namestring | nullnoThe credential’s Jira account, as Jira names it
has_tls_cabooleanno
default_targetJiraTargetyesWhere a new issue goes.
team_targetsobjectnoTeam id → target
product_targetsobjectnoProduct id → target
priority_by_severityobjectno
transitionsJiraTransitionsyesTransition names to use. A missing one is chosen by the status category it leads to.
rulesJiraRule[]yes
include_detailsbooleanyes
enabledbooleanyes
syncJiraSyncStateyes
created_atstring (date-time)yes
  • 404 — Not Found

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

NameTypeRequiredDescription
org_idstringyes

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
}
FieldTypeRequiredDescription
base_urlstringyesThe site’s root URL, e.g. https://acme.atlassian.net. Must be allowed by the deployment’s jira.egress policy.
flavor"cloud" | "data_center"yescloud (REST v3) or data_center (REST v2)
emailstring | nullnoCloud only: the email of the account the API token belongs to
api_tokenstring | nullnoCloud: an API token. Data Center: a personal access token. Write-only. Required on the first connect.
tls_ca_pemstring | nullnoData 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_targetJiraTargetyesWhere a new issue goes.
priority_by_severityobjectnoSeverity → Jira priority name. A severity left out sets no priority.
transitionsJiraTransitionsnoTransition names to use. A missing one is chosen by the status category it leads to.
rulesJiraRuleInput[]noWhen an issue is created without a click. Empty: only by a click.
include_detailsbooleannoOff: an issue carries title, rule, severity, resource and a dashboard link. On: also the analysis’s explanation and suggested next step.
enabledbooleannoOff 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"
}
FieldTypeRequiredDescription
base_urlstringyes
flavor"cloud" | "data_center"yes
emailstring | nullyes
account_namestring | nullnoThe credential’s Jira account, as Jira names it
has_tls_cabooleanno
default_targetJiraTargetyesWhere a new issue goes.
team_targetsobjectnoTeam id → target
product_targetsobjectnoProduct id → target
priority_by_severityobjectno
transitionsJiraTransitionsyesTransition names to use. A missing one is chosen by the status category it leads to.
rulesJiraRule[]yes
include_detailsbooleanyes
enabledbooleanyes
syncJiraSyncStateyes
created_atstring (date-time)yes
  • 400 — Bad Request
  • 403 — 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

NameTypeRequiredDescription
org_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"ok": true,
"account_name": "string",
"problems": [
"string"
]
}
FieldTypeRequiredDescription
okbooleanyes
account_namestring | nullno
problemsstring[]noWhat would stop an issue from being created
  • 403 — Forbidden
  • 404 — 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

NameTypeRequiredDescription
org_idstringyes
product_idstringyes

Request body (application/json)

{
"project_key": "string",
"issue_type": "Bug",
"labels": [
"string"
],
"components": [
"string"
]
}
FieldTypeRequiredDescription
project_keystringyese.g. SEC
issue_typestringnoThe issue type’s name
labelsstring[]noAdded to every issue, on top of opentremor and the finding’s own label
componentsstring[]noComponent 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"
}
FieldTypeRequiredDescription
base_urlstringyes
flavor"cloud" | "data_center"yes
emailstring | nullyes
account_namestring | nullnoThe credential’s Jira account, as Jira names it
has_tls_cabooleanno
default_targetJiraTargetyesWhere a new issue goes.
team_targetsobjectnoTeam id → target
product_targetsobjectnoProduct id → target
priority_by_severityobjectno
transitionsJiraTransitionsyesTransition names to use. A missing one is chosen by the status category it leads to.
rulesJiraRule[]yes
include_detailsbooleanyes
enabledbooleanyes
syncJiraSyncStateyes
created_atstring (date-time)yes
  • 400 — Bad Request
  • 403 — Forbidden
  • 404 — 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

NameTypeRequiredDescription
org_idstringyes
product_idstringyes

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"
}
FieldTypeRequiredDescription
base_urlstringyes
flavor"cloud" | "data_center"yes
emailstring | nullyes
account_namestring | nullnoThe credential’s Jira account, as Jira names it
has_tls_cabooleanno
default_targetJiraTargetyesWhere a new issue goes.
team_targetsobjectnoTeam id → target
product_targetsobjectnoProduct id → target
priority_by_severityobjectno
transitionsJiraTransitionsyesTransition names to use. A missing one is chosen by the status category it leads to.
rulesJiraRule[]yes
include_detailsbooleanyes
enabledbooleanyes
syncJiraSyncStateyes
created_atstring (date-time)yes
  • 403 — Forbidden
  • 404 — 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

NameTypeRequiredDescription
org_idstringyes
team_idstringyes

Request body (application/json)

{
"project_key": "string",
"issue_type": "Bug",
"labels": [
"string"
],
"components": [
"string"
]
}
FieldTypeRequiredDescription
project_keystringyese.g. SEC
issue_typestringnoThe issue type’s name
labelsstring[]noAdded to every issue, on top of opentremor and the finding’s own label
componentsstring[]noComponent 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"
}
FieldTypeRequiredDescription
base_urlstringyes
flavor"cloud" | "data_center"yes
emailstring | nullyes
account_namestring | nullnoThe credential’s Jira account, as Jira names it
has_tls_cabooleanno
default_targetJiraTargetyesWhere a new issue goes.
team_targetsobjectnoTeam id → target
product_targetsobjectnoProduct id → target
priority_by_severityobjectno
transitionsJiraTransitionsyesTransition names to use. A missing one is chosen by the status category it leads to.
rulesJiraRule[]yes
include_detailsbooleanyes
enabledbooleanyes
syncJiraSyncStateyes
created_atstring (date-time)yes
  • 400 — Bad Request
  • 403 — Forbidden
  • 404 — 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

NameTypeRequiredDescription
org_idstringyes
team_idstringyes

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"
}
FieldTypeRequiredDescription
base_urlstringyes
flavor"cloud" | "data_center"yes
emailstring | nullyes
account_namestring | nullnoThe credential’s Jira account, as Jira names it
has_tls_cabooleanno
default_targetJiraTargetyesWhere a new issue goes.
team_targetsobjectnoTeam id → target
product_targetsobjectnoProduct id → target
priority_by_severityobjectno
transitionsJiraTransitionsyesTransition names to use. A missing one is chosen by the status category it leads to.
rulesJiraRule[]yes
include_detailsbooleanyes
enabledbooleanyes
syncJiraSyncStateyes
created_atstring (date-time)yes
  • 403 — Forbidden
  • 404 — 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

NameTypeRequiredDescription
org_idstringyes

Query parameters

NameTypeRequiredDescription
dry_runbooleannoOnly count

Response 200 (application/json)

{
"findings": 0,
"applied": true
}
FieldTypeRequiredDescription
findingsintegeryesFindings the rules match that have no issue yet
appliedbooleanyesFalse for a dry run
  • 403 — Forbidden
  • 404 — Not Found

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

NameTypeRequiredDescription
org_idstringyes

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"
}
FieldTypeRequiredDescription
rulesOwnershipRule[]noTried 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_idstring | nullnoReviews 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

NameTypeRequiredDescription
org_idstringyes

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"
}
FieldTypeRequiredDescription
rulesOwnershipRule[]noTried 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_idstring | nullnoReviews 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"
}
FieldTypeRequiredDescription
rulesOwnershipRule[]noTried 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_idstring | nullnoReviews 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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"assigned": 4
}
FieldTypeRequiredDescription
assignedintegeryesUnowned repositories a rule gave teams to

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

NameTypeRequiredDescription
org_idstringyes

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"
}
]
}
FieldTypeRequiredDescription
team_idsstring[] | nullnoThe owning teams, replacing the current list. Empty unassigns.
product_idstring | nullnoThe product it belongs to. Null removes it from its product.
enabled_packsstring[] | nullnoPacks 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_variantsobject | nullnoPack name → variant, replacing the whole map. Each variant must be one the pack has.
llmRepositoryLlm | nullnoThe connection and model for this repository’s reviews. Null goes back to the integration’s.
knowledgeRepositoryKnowledge | nullnoFiles rules are drawn from, replacing the current list. Null stops reading them.
review_draftsboolean | nullnoWhether draft pull requests are reviewed. Null goes back to the default: they are not.
code_suggestionsboolean | nullnoPost code suggestions here, or not, whatever the org’s setting. Null follows the org.
repositoriesRepositoryKey[]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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyesThe host’s id for the repository — GitHub repository id, GitLab project id
full_namestringyesAs a person writes it: acme/infra, acme/platform/infra
status"active" | "removed"no
source"sync" | "webhook"yes
team_idsstring[]noOwning teams. Empty until someone assigns one.
product_idstring | nullnoThe product it belongs to, if any (models/catalog.py)
enabled_packsstring[] | nullnoPacks that run here on top of the org’s and the product’s. Null until someone sets it.
rule_variantsobjectnoPack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”}
excluded_rulesRuleExclusion[]noCustom rules turned off here, each with the reason
llmRepositoryLlm | nullnoNull: the integration’s connection and model
knowledgeRepositoryKnowledge | nullnoFiles rules are drawn from, such as ADRs. Null: none are read.
review_draftsboolean | nullnoWhether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false.
code_suggestionsboolean | nullnoPost code suggestions on this repository’s pull requests. Null: the org’s setting.
filled_byFilledBynoThe 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_syncKnowledgeSyncState | nullnoThe last sync of those files
scanScanState | nullnoThe last scan of the default branch. Null: never scanned.
suggested_packsstring[]noPacks 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_variantsobjectnoPack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it.
first_seen_atstring (date-time)yes
updated_atstring (date-time)yes
last_pull_request_atstring (date-time) | nullnoWhen 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_ids replaces the owning teams. [] unassigns it: reviews then go to its product’s teams, then the org’s default review team.
  • product_id is 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
org_idstringyes

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
}
FieldTypeRequiredDescription
team_idsstring[] | nullnoThe owning teams, replacing the current list. Empty unassigns.
product_idstring | nullnoThe product it belongs to. Null removes it from its product.
enabled_packsstring[] | nullnoPacks 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_variantsobject | nullnoPack name → variant, replacing the whole map. Each variant must be one the pack has.
llmRepositoryLlm | nullnoThe connection and model for this repository’s reviews. Null goes back to the integration’s.
knowledgeRepositoryKnowledge | nullnoFiles rules are drawn from, replacing the current list. Null stops reading them.
review_draftsboolean | nullnoWhether draft pull requests are reviewed. Null goes back to the default: they are not.
code_suggestionsboolean | nullnoPost 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"
}
FieldTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyesThe host’s id for the repository — GitHub repository id, GitLab project id
full_namestringyesAs a person writes it: acme/infra, acme/platform/infra
status"active" | "removed"no
source"sync" | "webhook"yes
team_idsstring[]noOwning teams. Empty until someone assigns one.
product_idstring | nullnoThe product it belongs to, if any (models/catalog.py)
enabled_packsstring[] | nullnoPacks that run here on top of the org’s and the product’s. Null until someone sets it.
rule_variantsobjectnoPack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”}
excluded_rulesRuleExclusion[]noCustom rules turned off here, each with the reason
llmRepositoryLlm | nullnoNull: the integration’s connection and model
knowledgeRepositoryKnowledge | nullnoFiles rules are drawn from, such as ADRs. Null: none are read.
review_draftsboolean | nullnoWhether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false.
code_suggestionsboolean | nullnoPost code suggestions on this repository’s pull requests. Null: the org’s setting.
filled_byFilledBynoThe 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_syncKnowledgeSyncState | nullnoThe last sync of those files
scanScanState | nullnoThe last scan of the default branch. Null: never scanned.
suggested_packsstring[]noPacks 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_variantsobjectnoPack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it.
first_seen_atstring (date-time)yes
updated_atstring (date-time)yes
last_pull_request_atstring (date-time) | nullnoWhen a pull or merge request on this repository last asked for a review
  • 404 — The repository list does not have it

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

NameTypeRequiredDescription
org_idstringyes

Query parameters

NameTypeRequiredDescription
provider"github" | "gitlab" | nullno
status"active" | "removed" | nullno
team_idstring | nullnoOnly repositories this team owns
product_idstring | nullnoOnly repositories in this product
unownedbooleannoOnly 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
repositorystringyesprovider/external_id
full_namestringyes
statusstringyesactive, or removed when the host no longer lists it
open_findingsobjectyesOpen, needs-review and acknowledged findings seen in it, by severity
changesetsintegeryesIts changesets: one per pull request reviewed
last_revision_atstring (date-time) | nullyesWhen 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
org_idstringyes

Query parameters

NameTypeRequiredDescription
formatReportOutput | nullnomarkdown (default), html or json. The response is the report itself: text/markdown, text/html, or the report data as JSON.
detailReportDetailnosummary keeps CRITICAL and HIGH findings only. On a changeset report in Markdown, it also uses the short pull request comment layout.
include_suppressedbooleannoAlso list findings triaged as suppressed or false positive
theme"light" | "dark" | nullnoHTML 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": [
{}
]
}
FieldTypeRequiredDescription
timestampstringyes
kind"product" | "repository"yes
titlestringyes
include_suppressedbooleanyes
totalsobjectyesFindings by severity, worst first
finding_countintegeryes
repositoriesobject[]yesOne section per repository: its activity, findings and recent changesets
top_rulesobject[]yesThe rules with the most findings
  • 404 — The repository list does not have it

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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"results": [
{
"provider": "github",
"listed": 0,
"added": 0,
"removed": 0,
"error": "string"
}
]
}
FieldTypeRequiredDescription
resultsRepositorySyncOutcome[]yesOne 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
rule_idstringyes
org_idstringyes

Request body (application/json)

{
"reason": "string"
}
FieldTypeRequiredDescription
reasonstringyesWhy 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"
}
FieldTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyesThe host’s id for the repository — GitHub repository id, GitLab project id
full_namestringyesAs a person writes it: acme/infra, acme/platform/infra
status"active" | "removed"no
source"sync" | "webhook"yes
team_idsstring[]noOwning teams. Empty until someone assigns one.
product_idstring | nullnoThe product it belongs to, if any (models/catalog.py)
enabled_packsstring[] | nullnoPacks that run here on top of the org’s and the product’s. Null until someone sets it.
rule_variantsobjectnoPack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”}
excluded_rulesRuleExclusion[]noCustom rules turned off here, each with the reason
llmRepositoryLlm | nullnoNull: the integration’s connection and model
knowledgeRepositoryKnowledge | nullnoFiles rules are drawn from, such as ADRs. Null: none are read.
review_draftsboolean | nullnoWhether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false.
code_suggestionsboolean | nullnoPost code suggestions on this repository’s pull requests. Null: the org’s setting.
filled_byFilledBynoThe 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_syncKnowledgeSyncState | nullnoThe last sync of those files
scanScanState | nullnoThe last scan of the default branch. Null: never scanned.
suggested_packsstring[]noPacks 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_variantsobjectnoPack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it.
first_seen_atstring (date-time)yes
updated_atstring (date-time)yes
last_pull_request_atstring (date-time) | nullnoWhen 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
rule_idstringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyesThe host’s id for the repository — GitHub repository id, GitLab project id
full_namestringyesAs a person writes it: acme/infra, acme/platform/infra
status"active" | "removed"no
source"sync" | "webhook"yes
team_idsstring[]noOwning teams. Empty until someone assigns one.
product_idstring | nullnoThe product it belongs to, if any (models/catalog.py)
enabled_packsstring[] | nullnoPacks that run here on top of the org’s and the product’s. Null until someone sets it.
rule_variantsobjectnoPack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”}
excluded_rulesRuleExclusion[]noCustom rules turned off here, each with the reason
llmRepositoryLlm | nullnoNull: the integration’s connection and model
knowledgeRepositoryKnowledge | nullnoFiles rules are drawn from, such as ADRs. Null: none are read.
review_draftsboolean | nullnoWhether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false.
code_suggestionsboolean | nullnoPost code suggestions on this repository’s pull requests. Null: the org’s setting.
filled_byFilledBynoThe 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_syncKnowledgeSyncState | nullnoThe last sync of those files
scanScanState | nullnoThe last scan of the default branch. Null: never scanned.
suggested_packsstring[]noPacks 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_variantsobjectnoPack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it.
first_seen_atstring (date-time)yes
updated_atstring (date-time)yes
last_pull_request_atstring (date-time) | nullnoWhen 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
org_idstringyes

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
}
FieldTypeRequiredDescription
team_idsstring[]yesOwning teams: the repository’s and its product’s. Rule scopes match on these
review_team_idsstring[]yesTeams the next review goes to: the owning teams, else the org’s default review team; empty for an org-wide review
product_idstring | nullyes
packsstring[]yesPacks that may run: the org’s enabled packs minus this repository’s
rule_variantsobjectyesThe variant each of those packs uses here
rule_idsstring[]yesCustom rules that apply here, after scope and exclusions
excluded_rulesRuleExclusion[]yes
llmRepositoryLlm | nullyesThe 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_draftsbooleanyesWhether a draft pull request is reviewed before it is marked ready
code_suggestionsbooleanyesWhether 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
pack_namestringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyesThe host’s id for the repository — GitHub repository id, GitLab project id
full_namestringyesAs a person writes it: acme/infra, acme/platform/infra
status"active" | "removed"no
source"sync" | "webhook"yes
team_idsstring[]noOwning teams. Empty until someone assigns one.
product_idstring | nullnoThe product it belongs to, if any (models/catalog.py)
enabled_packsstring[] | nullnoPacks that run here on top of the org’s and the product’s. Null until someone sets it.
rule_variantsobjectnoPack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”}
excluded_rulesRuleExclusion[]noCustom rules turned off here, each with the reason
llmRepositoryLlm | nullnoNull: the integration’s connection and model
knowledgeRepositoryKnowledge | nullnoFiles rules are drawn from, such as ADRs. Null: none are read.
review_draftsboolean | nullnoWhether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false.
code_suggestionsboolean | nullnoPost code suggestions on this repository’s pull requests. Null: the org’s setting.
filled_byFilledBynoThe 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_syncKnowledgeSyncState | nullnoThe last sync of those files
scanScanState | nullnoThe last scan of the default branch. Null: never scanned.
suggested_packsstring[]noPacks 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_variantsobjectnoPack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it.
first_seen_atstring (date-time)yes
updated_atstring (date-time)yes
last_pull_request_atstring (date-time) | nullnoWhen 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
pack_namestringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyesThe host’s id for the repository — GitHub repository id, GitLab project id
full_namestringyesAs a person writes it: acme/infra, acme/platform/infra
status"active" | "removed"no
source"sync" | "webhook"yes
team_idsstring[]noOwning teams. Empty until someone assigns one.
product_idstring | nullnoThe product it belongs to, if any (models/catalog.py)
enabled_packsstring[] | nullnoPacks that run here on top of the org’s and the product’s. Null until someone sets it.
rule_variantsobjectnoPack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”}
excluded_rulesRuleExclusion[]noCustom rules turned off here, each with the reason
llmRepositoryLlm | nullnoNull: the integration’s connection and model
knowledgeRepositoryKnowledge | nullnoFiles rules are drawn from, such as ADRs. Null: none are read.
review_draftsboolean | nullnoWhether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false.
code_suggestionsboolean | nullnoPost code suggestions on this repository’s pull requests. Null: the org’s setting.
filled_byFilledBynoThe 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_syncKnowledgeSyncState | nullnoThe last sync of those files
scanScanState | nullnoThe last scan of the default branch. Null: never scanned.
suggested_packsstring[]noPacks 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_variantsobjectnoPack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it.
first_seen_atstring (date-time)yes
updated_atstring (date-time)yes
last_pull_request_atstring (date-time) | nullnoWhen 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
pack_namestringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyesThe host’s id for the repository — GitHub repository id, GitLab project id
full_namestringyesAs a person writes it: acme/infra, acme/platform/infra
status"active" | "removed"no
source"sync" | "webhook"yes
team_idsstring[]noOwning teams. Empty until someone assigns one.
product_idstring | nullnoThe product it belongs to, if any (models/catalog.py)
enabled_packsstring[] | nullnoPacks that run here on top of the org’s and the product’s. Null until someone sets it.
rule_variantsobjectnoPack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”}
excluded_rulesRuleExclusion[]noCustom rules turned off here, each with the reason
llmRepositoryLlm | nullnoNull: the integration’s connection and model
knowledgeRepositoryKnowledge | nullnoFiles rules are drawn from, such as ADRs. Null: none are read.
review_draftsboolean | nullnoWhether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false.
code_suggestionsboolean | nullnoPost code suggestions on this repository’s pull requests. Null: the org’s setting.
filled_byFilledBynoThe 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_syncKnowledgeSyncState | nullnoThe last sync of those files
scanScanState | nullnoThe last scan of the default branch. Null: never scanned.
suggested_packsstring[]noPacks 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_variantsobjectnoPack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it.
first_seen_atstring (date-time)yes
updated_atstring (date-time)yes
last_pull_request_atstring (date-time) | nullnoWhen 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
pack_namestringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyesThe host’s id for the repository — GitHub repository id, GitLab project id
full_namestringyesAs a person writes it: acme/infra, acme/platform/infra
status"active" | "removed"no
source"sync" | "webhook"yes
team_idsstring[]noOwning teams. Empty until someone assigns one.
product_idstring | nullnoThe product it belongs to, if any (models/catalog.py)
enabled_packsstring[] | nullnoPacks that run here on top of the org’s and the product’s. Null until someone sets it.
rule_variantsobjectnoPack name → the rule variant to use here, e.g. {“terraform-plan”: “aws”}
excluded_rulesRuleExclusion[]noCustom rules turned off here, each with the reason
llmRepositoryLlm | nullnoNull: the integration’s connection and model
knowledgeRepositoryKnowledge | nullnoFiles rules are drawn from, such as ADRs. Null: none are read.
review_draftsboolean | nullnoWhether a draft pull request is reviewed. False: it gets a pending status and is reviewed once marked ready. Null: the same as false.
code_suggestionsboolean | nullnoPost code suggestions on this repository’s pull requests. Null: the org’s setting.
filled_byFilledBynoThe 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_syncKnowledgeSyncState | nullnoThe last sync of those files
scanScanState | nullnoThe last scan of the default branch. Null: never scanned.
suggested_packsstring[]noPacks 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_variantsobjectnoPack name → a variant the analysed content looks like it needs. Never applied on its own: apply or dismiss it.
first_seen_atstring (date-time)yes
updated_atstring (date-time)yes
last_pull_request_atstring (date-time) | nullnoWhen 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
org_idstringyes

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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
org_idstringyes

Response 202 (application/json)

{
"started": true
}
FieldTypeRequiredDescription
startedbooleanyesFalse when a sync of this repository is already running
  • 404 — Not Found
  • 409 — The repository has no knowledge sources

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
}
FieldTypeRequiredDescription
startedintegeryesRepositories 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
org_idstringyes

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
}
FieldTypeRequiredDescription
branchstringyes
commit_shastringyes
packsPackEstimate[]yesEvery pack that would read at least one file, with the most files first
unmatched_by_extensionobjectyesFiles no pack reads, grouped by extension
suggested_packsstring[]noPacks that claim files here but are not enabled for this repository. Stored on the repository as suggestions; enable one to scan with it.
excludedintegeryesFiles skipped as vendored, generated or oversized
testsintegeryesTest files, excluded from the counts above. A plan reads them with include_tests.
truncatedbooleanyesThe host listed only part of the tree
remaining_budget_usdnumber | nullyesWhat remains of this month’s LLM budget. Null means no cap.
  • 404 — Not Found
  • 409 — No integration is connected
  • 502 — 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
changesetstringyes
revision_idstringyes
commit_shastringyes
job_idstringyes
status"queued" | "running" | "done" | "stopped" | "failed"yes
planScanPlanyesWhat this run was asked to do
slices_doneScanSlice[]no
slices_leftScanSlice[]noWhat a resume runs
unitsintegernoUnits this run ingested
analysed_unitsintegernoUnits this run analysed
reused_unitsintegernoUnits already analysed before this run, whose analysis it reused without an LLM call
stopped_reasonstring | nullno
started_atstring (date-time)yes
finished_atstring (date-time) | nullno
  • 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

NameTypeRequiredDescription
provider"github" | "gitlab"yes
external_idstringyes
org_idstringyes

Request body (application/json)

{
"plan": {
"slices": [
{
"pack": "string",
"paths": [
"string"
],
"categories": [
"string"
]
}
],
"max_units": 1,
"include_tests": false
}
}
FieldTypeRequiredDescription
planScanPlan | nullnoThe 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"
}
FieldTypeRequiredDescription
changesetstringyes
revision_idstringyes
commit_shastringyes
job_idstringyes
status"queued" | "running" | "done" | "stopped" | "failed"yes
planScanPlanyesWhat this run was asked to do
slices_doneScanSlice[]no
slices_leftScanSlice[]noWhat a resume runs
unitsintegernoUnits this run ingested
analysed_unitsintegernoUnits this run analysed
reused_unitsintegernoUnits already analysed before this run, whose analysis it reused without an LLM call
stopped_reasonstring | nullno
started_atstring (date-time)yes
finished_atstring (date-time) | nullno
  • 404 — Not Found
  • 409 — A scan is already running, or no integration is connected

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).

List the org’s products

The org’s products, by name. Teams deleted since then are left out of team_ids.

Path parameters

NameTypeRequiredDescription
org_idstringyes

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"
}
]
}

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"name": "string",
"description": "string",
"team_ids": [
"string"
],
"repositories": [
{
"provider": "github",
"external_id": "string"
}
],
"enabled_packs": [
"string"
]
}
FieldTypeRequiredDescription
namestringyes
descriptionstring | nullno
team_idsstring[]noOwning teams
repositoriesRepositoryKey[]noRepositories to move into the product, out of any product they are in. Needs repositories:manage too.
enabled_packsstring[]noPacks 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"
}
FieldTypeRequiredDescription
product_idstringyes
namestringyes
descriptionstring | nullno
team_idsstring[]yesOwning teams; teams deleted since are left out
enabled_packsstring[]noPacks that run on every repository of the product, on top of the org’s
created_bystring | nullno
created_atstring (date-time)yes
updated_atstring (date-time) | nullno
  • 403 — repositories is set without the repositories:manage permission
  • 404 — 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

NameTypeRequiredDescription
product_idstringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
product_idstringyes
namestringyes
descriptionstring | nullno
team_idsstring[]yesOwning teams; teams deleted since are left out
enabled_packsstring[]noPacks that run on every repository of the product, on top of the org’s
created_bystring | nullno
created_atstring (date-time)yes
updated_atstring (date-time) | nullno
  • 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

NameTypeRequiredDescription
product_idstringyes
org_idstringyes

Request body (application/json)

{
"name": "string",
"description": "string",
"team_ids": [
"string"
],
"enabled_packs": [
"string"
]
}
FieldTypeRequiredDescription
namestring | nullno
descriptionstring | nullno
team_idsstring[] | nullno
enabled_packsstring[] | nullnoReplaces 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"
}
FieldTypeRequiredDescription
product_idstringyes
namestringyes
descriptionstring | nullno
team_idsstring[]yesOwning teams; teams deleted since are left out
enabled_packsstring[]noPacks that run on every repository of the product, on top of the org’s
created_bystring | nullno
created_atstring (date-time)yes
updated_atstring (date-time) | nullno
  • 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

NameTypeRequiredDescription
product_idstringyes
org_idstringyes

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

NameTypeRequiredDescription
product_idstringyes
org_idstringyes

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
}
}
FieldTypeRequiredDescription
product_idstringyes
namestringyes
repositoriesRepositoryActivity[]yes
open_findingsobjectyesBy 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

NameTypeRequiredDescription
product_idstringyes
org_idstringyes

Query parameters

NameTypeRequiredDescription
formatReportOutput | nullnomarkdown (default), html or json. The response is the report itself: text/markdown, text/html, or the report data as JSON.
detailReportDetailnosummary keeps CRITICAL and HIGH findings only. On a changeset report in Markdown, it also uses the short pull request comment layout.
include_suppressedbooleannoAlso list findings triaged as suppressed or false positive
theme"light" | "dark" | nullnoHTML 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": [
{}
]
}
FieldTypeRequiredDescription
timestampstringyes
kind"product" | "repository"yes
titlestringyes
include_suppressedbooleanyes
totalsobjectyesFindings by severity, worst first
finding_countintegeryes
repositoriesobject[]yesOne section per repository: its activity, findings and recent changesets
top_rulesobject[]yesThe rules with the most findings
  • 404 — Not Found

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

NameTypeRequiredDescription
product_idstringyes
org_idstringyes

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

NameTypeRequiredDescription
product_idstringyes
org_idstringyes

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"
}
]
}
FieldTypeRequiredDescription
titlestringyes
descriptionstring | nullnoWhat “done” looks like
status"draft" | "active" | "achieved" | "abandoned"no
target_datestring (date) | nullno
pathsstring[]noGlobs 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_keystring | nullnoThe goal’s Jira epic
stepsStepInput[]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

NameTypeRequiredDescription
product_idstringyes
goal_idstringyes
org_idstringyes

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

NameTypeRequiredDescription
product_idstringyes
goal_idstringyes
org_idstringyes

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

NameTypeRequiredDescription
product_idstringyes
goal_idstringyes
org_idstringyes

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

NameTypeRequiredDescription
product_idstringyes
goal_idstringyes
step_idstringyes
org_idstringyes

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

NameTypeRequiredDescription
product_idstringyes
goal_idstringyes
org_idstringyes

Query parameters

NameTypeRequiredDescription
limitintegerno

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

NameTypeRequiredDescription
product_idstringyes
goal_idstringyes
org_idstringyes

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 Request
  • 403 — Forbidden
  • 404 — Not Found
  • 409 — Conflict
  • 502 — Bad Gateway

Get the goal-check model

The LLM connection and model the goal check uses. Both null: the review’s own.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"connection_id": "string",
"model": "string"
}
FieldTypeRequiredDescription
connection_idstring | nullnoThe LLM connection the goal pass uses. Null: the connection of the review it runs in.
modelstring | nullnoThe model the goal pass uses, on connection_id. Set both or neither.

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"connection_id": "string",
"model": "string"
}
FieldTypeRequiredDescription
connection_idstring | nullnoThe LLM connection the goal pass uses. Null: the connection of the review it runs in.
modelstring | nullnoThe model the goal pass uses, on connection_id. Set both or neither.

Response 200 (application/json)

{
"connection_id": "string",
"model": "string"
}
FieldTypeRequiredDescription
connection_idstring | nullnoThe LLM connection the goal pass uses. Null: the connection of the review it runs in.
modelstring | nullnoThe model the goal pass uses, on connection_id. Set both or neither.

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.

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

NameTypeRequiredDescription
codestring | nullno
statestring | nullno
errorstring | nullno
  • 200
  • 307 — Temporary Redirect
  • 400 — Bad Request

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

NameTypeRequiredDescription
org_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

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"
}
FieldTypeRequiredDescription
labelstringyesHow 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.
eventsstring[]noEvent 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.
enabledbooleanno
team_idsstring[] | nullnoThe 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"yesWhich renderer formats the payload for this destination
target_urlstring (uri)yesWhere 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.
secretstring | nullnokind=‘webhook’ only. Signs the body with HMAC-SHA256 as X-Signature-256: sha256=. Meaningless for kind=‘slack’, whose endpoint neither expects nor verifies it. Write-only.
slack_mentionstring | nullnokind=‘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"
}
}
FieldTypeRequiredDescription
channel_idstringyes
labelstringyes
kind"slack" | "teams" | "webhook" | "email"yes
target_url_hintstring | nullnoHost and first path segment only — the full URL is never returned. Null for kind=‘email’.
recipientsChannelRecipient[] | nullnokind=‘email’ only. The active members among the stored recipients. Members who leave the organization are omitted and are not mailed.
has_secretbooleanyes
eventsstring[]yes
enabledbooleanyes
team_idsstring[] | nullnoNull: 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_mentionstring | nullno
created_atstring (date-time)yes
updated_atstring (date-time) | nullno
last_deliveryDeliveryRecord | nullno
provenance"manual" | "oauth"noHow 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.
slackSlackChannelInfo | nullno
  • 409 — The org already has notifications.max_channels_per_org channels (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

NameTypeRequiredDescription
org_idstringyes
channel_idstringyes

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"
}
}
FieldTypeRequiredDescription
channel_idstringyes
labelstringyes
kind"slack" | "teams" | "webhook" | "email"yes
target_url_hintstring | nullnoHost and first path segment only — the full URL is never returned. Null for kind=‘email’.
recipientsChannelRecipient[] | nullnokind=‘email’ only. The active members among the stored recipients. Members who leave the organization are omitted and are not mailed.
has_secretbooleanyes
eventsstring[]yes
enabledbooleanyes
team_idsstring[] | nullnoNull: 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_mentionstring | nullno
created_atstring (date-time)yes
updated_atstring (date-time) | nullno
last_deliveryDeliveryRecord | nullno
provenance"manual" | "oauth"noHow 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.
slackSlackChannelInfo | nullno
  • 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

NameTypeRequiredDescription
org_idstringyes
channel_idstringyes

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"
}
FieldTypeRequiredDescription
labelstring | nullno
target_urlstring (uri) | nullnoURL kinds only.
secretstring | nullno
clear_secretbooleannoRemove the signing secret. Distinguishes ‘leave it alone’ (omit secret) from ‘send unsigned from now on’.
recipientsstring[] | nullnokind=‘email’ only. Replaces the whole list.
eventsstring[] | nullno
enabledboolean | nullno
team_idsstring[] | nullnoThe 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_mentionstring | nullnokind=‘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"
}
}
FieldTypeRequiredDescription
channel_idstringyes
labelstringyes
kind"slack" | "teams" | "webhook" | "email"yes
target_url_hintstring | nullnoHost and first path segment only — the full URL is never returned. Null for kind=‘email’.
recipientsChannelRecipient[] | nullnokind=‘email’ only. The active members among the stored recipients. Members who leave the organization are omitted and are not mailed.
has_secretbooleanyes
eventsstring[]yes
enabledbooleanyes
team_idsstring[] | nullnoNull: 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_mentionstring | nullno
created_atstring (date-time)yes
updated_atstring (date-time) | nullno
last_deliveryDeliveryRecord | nullno
provenance"manual" | "oauth"noHow 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.
slackSlackChannelInfo | nullno
  • 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

NameTypeRequiredDescription
org_idstringyes
channel_idstringyes

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

NameTypeRequiredDescription
org_idstringyes
channel_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"manifest": {},
"target_url": "string",
"redirect_url": "string"
}
FieldTypeRequiredDescription
manifestobjectyesPaste into Slack’s Create New App → From a manifest
target_urlstringyesWhere to paste it — Slack’s app-creation page
redirect_urlstringyesThe 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

NameTypeRequiredDescription
org_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"client_id": "string",
"client_secret": "string"
}
FieldTypeRequiredDescription
client_idstringyesFrom the Slack app’s Basic Information page. Not a secret — it travels in the authorize URL — so it is returned by GET.
client_secretstringyesFrom 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

NameTypeRequiredDescription
org_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"authorize_url": "string",
"state": "string"
}
FieldTypeRequiredDescription
authorize_urlstringyes
statestringyesSingle-use CSRF token, echoed back by Slack on the callback
  • 404 — No Slack app stored yet
  • 501 — Not Implemented

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 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

NameTypeRequiredDescription
hash_resourcestringyesResource content hash

Query parameters

NameTypeRequiredDescription
filterstring | nullnoReturn 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 Request
  • 404 — Not Found

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. adjustments lists what the server changed: a quote the unit body does not contain is dropped, and a finding left with none is lowered to LOW confidence
  • rejected — not kept. errors names the finding and the field: a rule_id that is not in the unit’s ruleset, or a rule reported twice. Fix it and send that unit again
  • not_in_revision — the revision holds no such unit
  • claimed_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

NameTypeRequiredDescription
changesetstringyesChangeset

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"
]
}
]
}
]
}
FieldTypeRequiredDescription
revision_idstring | nullnoThe revision the units belong to; the current one when omitted
analysesSubmittedAnalysis[]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
}
}
FieldTypeRequiredDescription
resultsSubmissionResult[]yesOne per submitted analysis, in request order
progressLoopProgressyes
  • 403 — A viewer key
  • 404 — A changeset never ingested, or a revision_id it never had

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

NameTypeRequiredDescription
repositorystring | nullnoOnly this repository’s changesets (provider/external_id)
product_idstring | nullnoOnly 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 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

NameTypeRequiredDescription
changesetstringyesChangeset

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
}
}
FieldTypeRequiredDescription
changesetstringyes
created_atstring (date-time) | nullyesWhen its first revision started
current_revision_idstring | nullyes
revision_countintegeryes
repositorystring | nullyesprovider/external_id of the repository it belongs to, set once; null for an API analysis that named none
product_idstring | nullyesThe repository’s product now; null when it has none
pull_requestChangesetPullRequest | nullno
open_findingsobjectnoOpen, needs-review and acknowledged findings by severity
  • 404 — No such changeset

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

NameTypeRequiredDescription
changesetstringyesChangeset

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

NameTypeRequiredDescription
changesetstringyesChangeset
revisionstringyesRevision 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"
}
}
]
}
FieldTypeRequiredDescription
changesetstringyes
revision_idstringyes
previous_revision_idstring | nullyesThe revision this one is compared with
openedFindingRecord[]yes
closedFindingRecord[]yes
still_openFindingRecord[]yes
  • 404 — Not Found

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 — analyse units, submit, claim again
  • waiting — every remaining unit is claimed; claim again after retry_after_seconds, or release your own claims first if you lost track of them (DELETE /{changeset}/claims)
  • done — every unit has an analysis; fetch GET /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

NameTypeRequiredDescription
changesetstringyesChangeset

Request body (application/json, optional)

{
"limit": 5,
"revision_id": "string",
"known_rulesets": [
"string"
],
"known_contract": "string"
}
FieldTypeRequiredDescription
limitintegernoMost units to claim
revision_idstring | nullnoThe revision to drain; the current one when omitted
known_rulesetsstring[]noruleset_ids the caller already holds: their text is not sent again
known_contractstring | nullnoThe 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": {}
}
]
}
FieldTypeRequiredDescription
status"units" | "waiting" | "done"yesunits: 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
changesetstringyes
revision_idstring | nullyesThe revision drained; None for a changeset never ingested
progressLoopProgressyes
retry_after_secondsinteger | nullno
rulesetsobjectnoRulesets by ruleset_id, for the ids in units the request did not list in known_rulesets
contract_idstringyesId of the contract text, to list in known_contract
contractstring | nullnoHow to write each analysis, in Markdown. Sent with units unless the request named its id in known_contract
unitsClaimedUnit[]no
  • 403 — A viewer key
  • 404 — A revision_id the changeset never had

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

NameTypeRequiredDescription
changesetstringyesChangeset

Query parameters

NameTypeRequiredDescription
revisionstring | nullnoRevision id; the current revision when omitted
hashstring[] | nullnoRelease only these units; repeat it

Response 200 (application/json)

{
"released": 0
}
FieldTypeRequiredDescription
releasedintegeryesClaims of the caller’s that were handed back

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

NameTypeRequiredDescription
changesetstringyesChangeset

Query parameters

NameTypeRequiredDescription
revisionstring | nullnoRevision id; the current revision when omitted
  • 200

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, or json for the data the templates render.
  • detail=summary keeps CRITICAL and HIGH findings. In Markdown it uses the short pull request comment layout.
  • link=true mints a public, time-limited link to the full HTML report and puts it in the report. The link is built from server.dashboard_base_url, or server.public_base_url if that is unset, never from the request’s Host or X-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

NameTypeRequiredDescription
changesetstringyesChangeset

Query parameters

NameTypeRequiredDescription
formatReportOutput | nullnomarkdown (default), html or json. The response is the report itself: text/markdown, text/html, or the report data as JSON.
detailReportDetailnosummary keeps CRITICAL and HIGH findings only. On a changeset report in Markdown, it also uses the short pull request comment layout.
include_suppressedbooleannoAlso list findings triaged as suppressed or false positive
theme"light" | "dark" | nullnoHTML report theme: light or dark. Follows the reader’s system setting when omitted.
revisionstring | nullnoRevision id; the current revision when omitted
template_idstring | nullnoRender with this org report template instead of the org’s default. Without format, the template’s own format applies; with a different one, 422.
linkbooleannoMint 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": {}
}
FieldTypeRequiredDescription
timestampstringyes
changesetstringyes
revision_idstring | nullyes
packstringyespacks, joined with commas
packsstring[]yes
resource_countintegeryes
resourcesobject[]yesEach unit’s pack-specific fields, with hash, analysis (its findings, each with a triage status) and analysed_with
analysed_withAnalysedWith[]yes
report_html_urlstring | nullyesPublic, time-limited link; set by link=true
dashboard_urlstring | nullyes
since_previousobject | nullyesWhat this revision opened, closed and left open since the one before it
checked_categoriesobject[]yes{pack, categories} for each pack the revision limited to some rule categories
repositoryobject | nullyes
productobject | nullyes
pull_requestobject | nullyes
  • 404 — template_id names no template in this org

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

NameTypeRequiredDescription
changesetstringyesChangeset

Query parameters

NameTypeRequiredDescription
revisionstring | nullnoRevision 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
}
FieldTypeRequiredDescription
changesetstringyes
revision_idstringyesThe revision the answer is about
state"success" | "failure" | "pending"yessuccess 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
descriptionstringyesThe one line a commit status would carry
resource_countintegeryesUnits in the revision
unanalysed_countintegeryesUnits 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

NameTypeRequiredDescription
changesetstringyesChangeset

Query parameters

NameTypeRequiredDescription
revisionstring | nullnoRevision id; the current revision when omitted
include_suppressedbooleannoInclude findings triaged as suppressed/false_positive (hidden by default)

Response 201 (application/json)

{
"url": "string",
"expires_at": "2026-01-01T00:00:00Z"
}
FieldTypeRequiredDescription
urlstringyesPublic URL of the full HTML report
expires_atstring (date-time)yesWhen the link stops working (the org’s report-link TTL)
  • 404 — Unknown changeset, or a revision it does not have
  • 409 — Conflict

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.

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

NameTypeRequiredDescription
tokenstringyesReport link token

Query parameters

NameTypeRequiredDescription
theme"light" | "dark" | nullnoHTML report theme: light or dark. Follows the viewer’s system setting when omitted.
  • 200
  • 404 — Token unknown or expired; both return the same response on purpose

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"ttl_hours": 1
}
FieldTypeRequiredDescription
ttl_hoursintegeryes1 hour to 720 hours (30 days)

Response 200 (application/json)

{
"report_link_ttl_hours": 24
}

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.

List report templates for this org

The org’s report templates; filter by format and is_default. Any member.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Query parameters

NameTypeRequiredDescription
formatReportFormat | nullno
is_defaultboolean | nullno

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"
}
]
}

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"name": "string",
"format": "markdown",
"source": "string",
"is_default": false
}
FieldTypeRequiredDescription
namestringyes
formatReportFormatyesWhat 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).
sourcestringyesJinja2 template source
is_defaultbooleanno

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"
}
FieldTypeRequiredDescription
template_idstringyes
org_idstringyes
namestringyes
formatReportFormatyesWhat 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).
sourcestringyes
is_defaultbooleanno
is_builtin_seedbooleannoTrue 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_bystring | nullyes
created_atstringyes
updated_atstring | nullno
  • 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

NameTypeRequiredDescription
template_idstringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
template_idstringyes
org_idstringyes
namestringyes
formatReportFormatyesWhat 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).
sourcestringyes
is_defaultbooleanno
is_builtin_seedbooleannoTrue 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_bystring | nullyes
created_atstringyes
updated_atstring | nullno
  • 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

NameTypeRequiredDescription
template_idstringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
template_idstringyes
org_idstringyes
namestringyes
formatReportFormatyesWhat 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).
sourcestringyes
is_defaultbooleanno
is_builtin_seedbooleannoTrue 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_bystring | nullyes
created_atstringyes
updated_atstring | nullno
  • 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

NameTypeRequiredDescription
template_idstringyes
org_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"created": 0,
"updated": 0,
"disabled": 0
}
FieldTypeRequiredDescription
createdintegeryes
updatedintegernoBuilt-in rules whose wording an org never edited, brought in line with the pack file
disabledintegernoBuilt-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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"source": "string",
"format": "markdown",
"changeset": "string"
}
FieldTypeRequiredDescription
sourcestringyes
formatReportFormatyesWhat 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).
changesetstring | nullnoAn 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 — changeset has no resources yet
  • 409 — No changeset, and no installed pack ships a demo sample