Skip to content
DashboardWebsite

Endpoints: Packs & Rules

A pack reads one kind of input (a terraform plan, a code diff, …), splits it into analysis units and ships the rules they are analysed against. ingest registers units for the client-led loop, where the caller’s own agent analyses them (POST /{changeset}/claims, then POST /{changeset}/analyses); analyze has the server call the LLM itself. The /auto forms route each file of a diff to the pack whose file_globs match it, so the caller need not know which pack applies.

List available pack backends

The manifest of every pack enabled for the caller’s organization, with enabled: true. With repository, the packs that run on that repository: the org’s, its product’s and its own. With all, every pack installed on this server, each with whether it is enabled at that level: what a person picks from when enabling one.

rules_by_category counts the pack’s rules that run there, per category id: the categories an analysis can choose from.

Query parameters

NameTypeRequiredDescription
repositorystring | nullnoprovider/external_id: list the packs that run on this repository
allbooleannoAlso list the packs that are off

Response 200 (application/json)

{
"packs": [
{
"name": "terraform-plan",
"description": "Analyses terraform plan output…"
}
]
}

Get the security ruleset for a pack

The Markdown ruleset (text/markdown) the LLM must apply to resources produced by {pack_name}. Pass the whole response as the analysis instructions before calling POST /{changeset}/analyses.

rule_type picks a sub-category (aws, gcp, …). repository returns that repository’s rules: its rule variant when rule_type is not set, its scoped rules, without the rules it turned off.

Path parameters

NameTypeRequiredDescription
pack_namestringyesPack name

Query parameters

NameTypeRequiredDescription
rule_typestring | nullnoRule sub-category filter
repositorystring | nullnoprovider/external_id of the repository this comes from: its rule variants, scoped rules, exclusions and enabled packs apply
  • 200
  • 404 — Pack not found, no rule file for that type, or the repository is not listed
  • 501 — The pack does not support rules yet

Get one built-in rule of a pack

What a built-in rule id such as TFSEC-040 means. A finding’s rule_id and its tags use these ids until the org imports the ruleset. Requires analysis:read (member). The rules come from the pack’s rule files as shipped; the org’s custom rules do not change them. Each variant’s file can word an id differently, so there is one entry per file that defines it, with the default variant first.

Path parameters

NameTypeRequiredDescription
pack_namestringyesPack name
rule_idstringyesBuilt-in rule ID

Response 200 (application/json)

{
"pack": "terraform-plan",
"rule_id": "TFSEC-040",
"variants": [
{
"rule_type": "aws",
"title": "string",
"severity": "CRITICAL",
"category": "string",
"description": "string"
}
]
}
FieldTypeRequiredDescription
packstringyes
rule_idstringyes
variantsPackRuleVariant[]yesOne entry per rule file that defines the rule, with the default variant first.
  • 404 — Pack not found, or no rule file of the pack defines rule_id

Ingest raw input and split it into analysis units

Parse and split the raw {pack_name} input into individual resource units, then register each unit under one revision of {changeset}.

This is the entry point of the client-led loop.

POST /{pack}/{changeset}/ingest → parse & split (this endpoint)
loop:
POST /{changeset}/claims → a batch of units + rules; status units|waiting|done
POST /{changeset}/analyses → submit the batch
GET /changesets/{changeset}/report → the report

The answer is a receipt: the revision, the unit count and each unit’s hash, type, name and action. Unit bodies are not sent back: a claim hands them out.

Each call starts a new revision, unless revision names the changeset’s current one: the units are then added to it. Ingest several packs into one revision that way.

repository and rule_type are stored on the revision, and every claim builds the rules from them. A unit already analysed in this organization keeps its analysis.

Input size is capped by server.max_input_size_mb (default 10 MB). A 501 means the pack exists but cannot ingest yet.

Path parameters

NameTypeRequiredDescription
pack_namestringyesPack name
changesetstringyesLogical grouping for this analysis run

Query parameters

NameTypeRequiredDescription
repositorystring | nullnoprovider/external_id of the repository this comes from: its rule variants, scoped rules, exclusions and enabled packs apply
rule_typestring | nullnoRule variant for this pack’s units (e.g. aws); the repository’s or the pack’s default when omitted
revisionstring | nullnoAdd the units to this revision, which must be the changeset’s current one, instead of starting a new one

Request body (text/plain)

Response 200 (application/json)

{
"changeset": "string",
"revision_id": "string",
"unit_count": 0,
"pending_count": 0,
"units": [
{
"unit_hash": "string",
"type": "string",
"name": "string",
"action": "string",
"pack": "string"
}
]
}
FieldTypeRequiredDescription
changesetstringyes
revision_idstringyesThe revision the units landed in. Pass it to claims, report and gate
unit_countintegeryesUnits this call parsed
pending_countintegeryesUnits of the revision with no analysis yet, all ingests included
unitsUnitSummary[]yes

Response 201 (application/json) — Units ingested

{
"changeset": "string",
"revision_id": "string",
"unit_count": 0,
"pending_count": 0,
"units": [
{
"unit_hash": "string",
"type": "string",
"name": "string",
"action": "string",
"pack": "string"
}
]
}
FieldTypeRequiredDescription
changesetstringyes
revision_idstringyesThe revision the units landed in. Pass it to claims, report and gate
unit_countintegeryesUnits this call parsed
pending_countintegeryesUnits of the revision with no analysis yet, all ingests included
unitsUnitSummary[]yes
  • 404 — Unknown pack, the repository is not listed, or the pack is not enabled here
  • 409 — revision is not the current one, or was ingested for another repository
  • 413 — Input over server.max_input_size_mb
  • 501 — The pack does not support ingestion

Server-side analysis: ingest and analyze in one call

Alternative to the client-led ingest → loop → report workflow — the server itself calls the LLM to analyse every unit and returns the report directly.

Small inputs (at most server.sync_analysis_max_units units) run inline and return the report immediately (200). Larger inputs are processed as a background job (202) — poll GET /jobs/{job_id} for status.

LLM credentials: pass api_key in the request body, or omit it to fall back to the secret on the named connection (POST /orgs/{org_id}/llm-connections).

Path parameters

NameTypeRequiredDescription
pack_namestringyesPack name
changesetstringyesLogical grouping for this analysis run

Request body (application/json)

{
"connection_id": "string",
"model": "string",
"api_key": "string",
"raw_input": "string",
"rule_type": "string",
"categories": [
"performance",
"reliability"
],
"repository": {
"provider": "github",
"external_id": "string"
}
}
FieldTypeRequiredDescription
connection_idstringyesThe LLM endpoint to call: a stored connection of this org (GET /orgs/{org_id}/llm-connections), or a hosted provider kind (anthropic, openai, …) used with an inline api_key and nothing stored.
modelstringyesProvider-specific model name, e.g. ‘claude-sonnet-5’
api_keystring | nullnoLLM provider API key for this call. Never stored. If omitted, falls back to the secret on the named connection. When both are present this key is used against that connection’s endpoint — it overrides the credential, never the address.
raw_inputstringyesRaw pack input text, same as POST …/ingest
rule_typestring | nullnoRule sub-category filter, e.g. ‘aws’
categoriesstring[] | nullnoRule category ids to check: each pack runs only its rules in them. Null runs every rule. Each unit is still one LLM call. The run closes no finding, and a later full analysis of the same code runs and is billed again.
repositoryRepositoryKey | nullnoThe repository this input comes from, as listed by GET /orgs/{org_id}/repositories. The run then gets that repository’s scoped rules, rule variants, exclusions and disabled packs. Omitted: org-wide rules and the org’s packs only.

Response 200 (application/json)

{
"job_id": "string",
"revision_id": "string",
"report_markdown": "string",
"resource_count": 0,
"quota_exceeded": false,
"packs_used": [
"string"
],
"detections": [
{}
]
}
FieldTypeRequiredDescription
job_idstringyesThe job this run was recorded as. An inline (sync) run gets a job document too — same as the async path’s 202 — so every analysis, however small, is one thing you can look up, resume and audit. See GET /jobs/{job_id}.
revision_idstringyesThe revision of the changeset this run ingested.
report_markdownstringyes
resource_countintegeryes
quota_exceededbooleannoTrue if the org’s monthly LLM budget was hit mid-run — the report is partial.
packs_usedstring[]noPacks actually invoked. Empty for the explicit-pack /analyze endpoint (the caller already knows); populated for /analyze/auto.
detectionsobject[]noAuto-routing audit trail (/analyze/auto only): one entry per file/blob with its detected content type, the pack it was routed to (null if none matched), and — when null — why, so no content is silently dropped from the report.

Response 202 (application/json)

{
"job_id": "string",
"status": "queued",
"revision_id": "string"
}
FieldTypeRequiredDescription
job_idstringyes
statusstringyes
revision_idstringyesThe revision of the changeset this job analyses.
  • 400 — No api_key given and none on the connection, or (provider kind, model) is not on the allowed-models catalog
  • 402 — The org’s monthly spend cap is already reached, or the org is not entitled; checked before any work starts
  • 404 — Unknown pack, the pack is not enabled here, or the repository is not listed
  • 413 — Input over server.max_input_size_mb
  • 501 — The pack does not support ingestion
  • 502 — The LLM’s output could not be parsed, or it stopped at analysis.llm_max_output_tokens (sync path only; the async path records it on the job). The body carries job_id

Auto-detect content type and ingest, fanning out across every matching pack

Like POST /{pack_name}/{changeset}/ingest, but without naming a pack: each file in a unified diff is routed to whichever registered pack’s file_globs matches its path (a diff touching .tf + .py + .md files runs the .tf parts through terraform-code-change and reports the rest as unmatched, instead of silently discarding them). A single non-diff blob is matched by content via each pack’s optional sniff() hook.

Response includes packs_used and a detections audit trail — one entry per file/blob with its detected content type and either the pack it was routed to, or a reason explaining why nothing matched.

Path parameters

NameTypeRequiredDescription
changesetstringyesLogical grouping for this analysis run

Query parameters

NameTypeRequiredDescription
repositorystring | nullnoprovider/external_id of the repository this comes from: its rule variants, scoped rules, exclusions and enabled packs apply
revisionstring | nullnoAdd the units to this revision, which must be the changeset’s current one, instead of starting a new one

Request body (text/plain)

Response 201 (application/json) — At least one file or blob matched a pack

{
"changeset": "gh-acme-infra-42",
"revision_id": "0c4d...",
"unit_count": 1,
"pending_count": 1,
"units": [
{
"hash": "a3f1c2d4e5b6",
"type": "aws_db_instance",
"name": "orders",
"action": "create",
"pack": "terraform-code-change"
}
],
"packs_used": [
"terraform-code-change",
"generic"
],
"detections": [
{
"path": "main.tf",
"detected_kind": "hcl",
"pack": "terraform-code-change",
"confidence": 1,
"fallback": false
},
{
"path": "README.md",
"detected_kind": "markdown",
"pack": "generic",
"confidence": 0,
"reason": "no pack available for this file type",
"fallback": true
}
]
}
  • 200
  • 409 — revision is not the changeset’s current revision, or names another repository
  • 413 — Input over server.max_input_size_mb

Auto-detect content type and analyze, fanning out across every matching pack

Server-side counterpart to POST /{changeset}/ingest/auto — ingest and analyze in one call, same auto-routing as above. Each matched pack’s own default_rule_type ruleset is used for its own units — unlike the explicit /analyze endpoint, a single rule_type override isn’t accepted here, since it wouldn’t mean the same thing across different packs in one run.

Same sync-vs-background-job split as /analyze: small inputs (at most server.sync_analysis_max_units units, summed across every matched pack) run inline and return the report immediately (200); larger inputs run as a background job (202) — poll GET /jobs/{job_id}.

Path parameters

NameTypeRequiredDescription
changesetstringyesLogical grouping for this analysis run

Request body (application/json)

{
"connection_id": "string",
"model": "string",
"api_key": "string",
"raw_input": "string",
"rule_type": "string",
"categories": [
"performance",
"reliability"
],
"repository": {
"provider": "github",
"external_id": "string"
}
}
FieldTypeRequiredDescription
connection_idstringyesThe LLM endpoint to call: a stored connection of this org (GET /orgs/{org_id}/llm-connections), or a hosted provider kind (anthropic, openai, …) used with an inline api_key and nothing stored.
modelstringyesProvider-specific model name, e.g. ‘claude-sonnet-5’
api_keystring | nullnoLLM provider API key for this call. Never stored. If omitted, falls back to the secret on the named connection. When both are present this key is used against that connection’s endpoint — it overrides the credential, never the address.
raw_inputstringyesRaw pack input text, same as POST …/ingest
rule_typestring | nullnoRule sub-category filter, e.g. ‘aws’
categoriesstring[] | nullnoRule category ids to check: each pack runs only its rules in them. Null runs every rule. Each unit is still one LLM call. The run closes no finding, and a later full analysis of the same code runs and is billed again.
repositoryRepositoryKey | nullnoThe repository this input comes from, as listed by GET /orgs/{org_id}/repositories. The run then gets that repository’s scoped rules, rule variants, exclusions and disabled packs. Omitted: org-wide rules and the org’s packs only.

Response 200 (application/json)

{
"job_id": "string",
"revision_id": "string",
"report_markdown": "string",
"resource_count": 0,
"quota_exceeded": false,
"packs_used": [
"string"
],
"detections": [
{}
]
}
FieldTypeRequiredDescription
job_idstringyesThe job this run was recorded as. An inline (sync) run gets a job document too — same as the async path’s 202 — so every analysis, however small, is one thing you can look up, resume and audit. See GET /jobs/{job_id}.
revision_idstringyesThe revision of the changeset this run ingested.
report_markdownstringyes
resource_countintegeryes
quota_exceededbooleannoTrue if the org’s monthly LLM budget was hit mid-run — the report is partial.
packs_usedstring[]noPacks actually invoked. Empty for the explicit-pack /analyze endpoint (the caller already knows); populated for /analyze/auto.
detectionsobject[]noAuto-routing audit trail (/analyze/auto only): one entry per file/blob with its detected content type, the pack it was routed to (null if none matched), and — when null — why, so no content is silently dropped from the report.

Response 202 (application/json)

{
"job_id": "string",
"status": "queued",
"revision_id": "string"
}
FieldTypeRequiredDescription
job_idstringyes
statusstringyes
revision_idstringyesThe revision of the changeset this job analyses.
  • 400 — No api_key given and none on the connection, or (provider kind, model) is not on the allowed-models catalog
  • 402 — The org’s monthly spend cap is already reached, or the org is not entitled; checked before any work starts
  • 502 — The LLM’s output could not be parsed, or it stopped at analysis.llm_max_output_tokens (sync path only; the async path records it on the job). The body carries job_id

List built-in packs with this org’s enabled/disabled state

Every registered pack with this org’s enabled state. A pack starts disabled; an enabled pack runs on every repository of the org. Requires the org’s admin role. repository_url is where the pack’s source lives (null when it declares none); file_globs are the paths auto-routing hands it; detects_content indicates whether it can also be recognised from pasted content alone; license is the licence declared by the pack’s package (null when it declares none).

In the dashboard: Rules → Packs.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"packs": [
{
"name": "terraform-plan",
"description": "Analyses terraform plan output…",
"version": "1.0.0",
"repository_url": "https://github.com/opentremor/OpenTremor-pack-terraform-plan",
"file_globs": [],
"detects_content": true,
"rule_types": [
"aws"
],
"default_rule_type": "generic",
"license": "Apache-2.0",
"has_demo": true,
"enabled": true,
"entitled": true
}
]
}

Enable or disable a built-in pack for this org

Turns a registered pack on or off for the whole org. Requires the org’s admin role. An enabled pack runs on every repository; a pack enabled only on a product or a repository runs only there. Ingest and analyze on a pack enabled nowhere for the request return 404.

Path parameters

NameTypeRequiredDescription
org_idstringyes
pack_namestringyes

Request body (application/json)

{
"enabled": true
}

Response 200 (application/json)

{
"pack_name": "terraform-code-change",
"enabled": false
}
  • 404 — pack_name is not a registered pack

DELETE /v1/orgs/{org_id}/packs/{pack_name}

Section titled “DELETE /v1/orgs/{org_id}/packs/{pack_name}”

Disable a built-in pack for this org (shorthand for POST enabled=false)

Shorthand for POST with {"enabled": false}. Requires the org’s admin role.

Path parameters

NameTypeRequiredDescription
org_idstringyes
pack_namestringyes
  • 200
  • 404 — pack_name is not a registered pack

Every server-side analysis is recorded as a job, inline (mode: "sync") or in the background (mode: "async"), whatever triggered it: the API, the dashboard or a code-host webhook. A background job runs on the platform’s job queue: any replica’s worker may run it, and a replica that dies mid-run hands it to another, except a job started with an inline api_key, which only the accepting replica can rebuild.

List analysis jobs for the caller’s org

The org’s analysis jobs, newest first, paged. Filter by status (queued, running, done, failed, cancelled). Covers every trigger, including the dashboard and code-host webhooks: it is the only place to see a webhook-triggered job.

In the dashboard: Analysis → Jobs.

Query parameters

NameTypeRequiredDescription
statusstring | nullnoqueued|running|done|failed|cancelled
limitintegerno
offsetintegerno

Response 200 (application/json)

{
"jobs": [
{
"job_id": "string",
"org_id": "string",
"mode": "sync",
"status": "queued",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z",
"finished_at": "2026-01-01T00:00:00Z",
"processed_count": 0,
"total_count": 0,
"retry_of": "string",
"error": "string",
"trigger": "api",
"kind": "string",
"attempts": 0,
"request_id": "string",
"external_ref": {},
"changeset": "string",
"revision_id": "string",
"pack": "string",
"llm_backend": "string",
"connection_id": "string",
"model": "string",
"rule_type": "string",
"repository": {
"provider": "github",
"external_id": "string"
},
"packs_used": [
"string"
],
"detections": [
{}
],
"injection_detections": [
{}
],
"injection_scoring": {
"scored": 0,
"stopped": "string",
"cost_usd": 0
},
"resource_count": 0,
"calibration_snapshot_id": "string",
"current_resource": {},
"quota_exceeded": false
}
],
"total": 0
}

Get analysis job status

Poll this after an .../analyze call returns 202. status goes queued → running → done, failed or cancelled. Once done, read the report with GET /changesets/{changeset}/report; a cancelled job also leaves a report of what it analysed.

pack is "auto" for a job from /analyze/auto or a webhook; packs_used and detections then carry the breakdown, and are empty for an explicit-pack job.

current_resource is the resource the loop most recently completed. The loop analyses a batch concurrently (analysis.max_concurrent_units, 4 by default), so while running it is roughly where the job is; processed_count and total_count are the exact measure. It is null until one resource is done, and is not cleared at the end.

Path parameters

NameTypeRequiredDescription
job_idstringyesJob ID returned by POST …/analyze

Response 200 (application/json)

{
"job_id": "string",
"org_id": "string",
"mode": "sync",
"status": "queued",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z",
"finished_at": "2026-01-01T00:00:00Z",
"processed_count": 0,
"total_count": 0,
"retry_of": "string",
"error": "string",
"trigger": "api",
"kind": "string",
"attempts": 0,
"request_id": "string",
"external_ref": {},
"changeset": "string",
"revision_id": "string",
"pack": "string",
"llm_backend": "string",
"connection_id": "string",
"model": "string",
"rule_type": "string",
"repository": {
"provider": "github",
"external_id": "string"
},
"packs_used": [
"string"
],
"detections": [
{}
],
"injection_detections": [
{}
],
"injection_scoring": {
"scored": 0,
"stopped": "string",
"cost_usd": 0
},
"resource_count": 0,
"calibration_snapshot_id": "string",
"current_resource": {},
"quota_exceeded": false
}
FieldTypeRequiredDescription
job_idstringyes
org_idstringyes
mode"sync" | "async"yes
status"queued" | "running" | "done" | "failed" | "cancelled"yes
created_atstring (date-time)yes
updated_atstring (date-time) | nullnoStamped by every PlatformStorageBackend.update_job call (status transitions and progress reports alike) — what POST /admin/jobs/sweep compares against jobs.stuck_timeout_minutes. Absent on a job created before this field existed, in which case the sweep skips it.
finished_atstring (date-time) | nullno
processed_countinteger | nullnoUnits of work completed so far.
total_countinteger | nullnoTotal units this run will process — set alongside the first progress update.
retry_ofstring | nullnojob_id of the original job this run resumed, if it was created as a retry.
errorstring | nullno
trigger"api" | "scm_webhook" | "repository_scan"no
kindstring | nullnoThe queued job kind a worker runs it as; null for a job run in the replica that accepted it.
attemptsinteger | nullnoHow many times a worker has claimed it — above 1 when a worker died mid-run.
request_idstring | nullnoX-Request-ID of the request that created the job. The job’s log lines carry it too.
external_refobject | nullnoProvider-specific origin, e.g. {‘provider’: ‘example’, ‘id’: ‘42’}
changesetstringyes
revision_idstringyesThe revision of changeset this job ingested and analyses. A retry resumes the same revision, even after the changeset has moved on.
packstringyesPack name, or the literal ‘auto’ for a job created via /{changeset}/ingest|analyze/auto or the GitHub webhook — see packs_used for the actual breakdown in that case.
llm_backendstring | nullyesProvider kind this run called. Null for a client-led repository scan, which calls none.
connection_idstring | nullnoThe connection this run called — what POST /jobs/{job_id}/retry resumes against. Null only on a webhook job whose GitHub integration had no connection configured yet.
modelstring | nullyesThe model this run called. Null for a client-led repository scan.
rule_typestring | nullno
repositoryRepositoryKey | nullnoThe repository the run was scoped to, if any
packs_usedstring[]noPopulated only when pack == ‘auto’.
detectionsobject[]noAuto-routing audit trail — see AnalyzeResponse.detections. Populated only when pack == ‘auto’.
injection_detectionsobject[]noAgent-injection signals found in the change (libs/injection_scan) — each with rule_id, severity, quotes, and the path/channel/line it was found in. Separate from detections, which is the auto-routing audit trail: these are findings, and they also appear in the report and the findings list like any other. Populated on GitHub-webhook jobs.
injection_scoringInjectionScoring | nullnoWhat semantic injection scoring did on this pull request, paid by the org (core ADR 0033). Null when it did not run: the platform does not allow it, or the org has not turned it on.
resource_countinteger | nullno
calibration_snapshot_idstring | nullnoContent hash of the reviewer-calibration block this run’s analysis prompts carried (services/feedback/calibration.py), or null if the run was uncalibrated — no qualifying feedback yet, or calibration switched off. A report is an audit artifact, so a run records what the pack was told about this org at the time; two runs of the same input carrying different ids differ for a reason that is now on the record.
current_resourceobject | nullnohash/unit_address/type of the resource most recently completed by the analysis loop. The loop analyses a batch concurrently (config.analysis.max_concurrent_units), so while status==‘running’ this is one of the resources in flight rather than the only one — treat it as ‘roughly where the job is’, with processed_count/total_count as the exact measure. Not cleared on completion (reflects the last resource processed).
quota_exceededbooleanno
  • 404 — Unknown job, or it belongs to another org

Cancel a queued or running analysis job

Stops a queued or running job, so it stops spending the org’s LLM budget. Works for every trigger.

Cancellation is cooperative: the runner checks between batches of concurrent LLM calls, so a running job stops within about one call’s latency. Calls already in flight are paid for either way, and their results are kept; processed_count says how far it got. was is the status at cancellation: queued never reached the LLM, running stops after its current batch.

A cancelled job is terminal but resumable: POST /jobs/{job_id}/retry re-analyses, and re-bills, only what the original run did not finish.

A cancelled code-host job posts nothing to the pull request: no comment, no commit status. A partial report read as a complete one is worse than none. Push a new commit to re-trigger the check; it analyses only what the cancelled run did not reach.

Path parameters

NameTypeRequiredDescription
job_idstringyesjob_id of the queued/running job to cancel

Response 200 (application/json)

{
"job_id": "string",
"status": "cancelled",
"was": "queued"
}
FieldTypeRequiredDescription
job_idstringyes
statusstringyes
was"queued" | "running"yesThe status the job was in when it was cancelled. ‘queued’ means it never reached the LLM at all; ‘running’ means it stops after its current batch of in-flight calls settles, which have already been paid for.
  • 404 — Unknown job, or it belongs to another org
  • 409 — The job already finished (done, failed, cancelled), or it is a mode: "sync" job, which lives inside its request and has nothing left to stop

Resume a stopped or incomplete analysis job

Resumes, under a new job_id, a job that stopped with work left: failed, cancelled, or done with quota_exceeded (a run that hit the monthly budget and returned a partial report). The original is left untouched; retry_of links back to it. The changeset, its revision, the pack and the connection, model and rule type come from the original job; only units with no analysis yet are processed. A resumed job always runs in the background (mode: "async").

api_key is never stored, so it falls back to the key on the job’s connection: the only option when the original request passed a one-off key.

Only the analysis phase can resume. raw_input is never persisted, so a job that stopped before ingest finished has nothing to resume: resubmit the original request. Code-host webhook jobs are not retryable here: a new commit to the pull request re-triggers them.

In the dashboard: Analysis → Jobs, then expand the job.

Path parameters

NameTypeRequiredDescription
job_idstringyesjob_id of the failed job to retry

Request body (application/json, optional)

{
"api_key": "string"
}
FieldTypeRequiredDescription
api_keystring | nullnoLLM provider API key for this retry. Never stored. If omitted, falls back to the secret on the job’s stored connection (POST /orgs/{org_id}/llm-connections) — the same fallback POST …/analyze itself uses, and the only option available since the original job’s api_key (if the caller passed one instead of relying on a stored credential) was never persisted either.

Response 202 (application/json)

{
"job_id": "string",
"status": "queued",
"retry_of": "string"
}
FieldTypeRequiredDescription
job_idstringyes
statusstringyes
retry_ofstringyesjob_id of the original failed job this run resumes.
  • 200
  • 400 — No api_key given and none on the connection, or (provider kind, model) is not on the allowed-models catalog
  • 402 — The org’s monthly spend cap is already reached, or the org is not entitled
  • 404 — Unknown job, or it belongs to another org
  • 409 — Nothing left to analyse (a plain done, or still queued or running), or a code-host webhook job

Sample findings an organization can explore before its first real run: a demo changeset built from the first enabled pack that ships a sample (analysis.demo_preferred_packs sets the order), plus the agent-manipulation findings the injection scanner raises on a sample pull request. No LLM is called; nothing is billed, counted against a trial, notified or recorded as reviewer feedback. demo is a reserved changeset name: ingest and analyze calls answer 422 for it.

Whether a demo analysis can be loaded, and whether one is

Requires findings:summary (viewer and up). available: an installed pack ships a demo sample. loaded: the org’s demo changeset exists. agent_scan_enabled: analysis.injection_scan_enabled; when false, a loaded demo holds the pack’s findings only.

Response 200 (application/json)

{
"available": true,
"loaded": true,
"agent_scan_enabled": true
}
FieldTypeRequiredDescription
availablebooleanyesSome pack enabled for this organization ships a demo sample.
loadedbooleanyesThe organization’s demo changeset exists.
agent_scan_enabledbooleanyesAgent-manipulation detection is on for this deployment. When it is off, a loaded demo holds the pack’s findings only.

Load the demo analysis

Writes a demo changeset: a sample change from the first installed pack that ships one, analysed in advance, plus the agent-manipulation findings the scanner raises on the sample pull request. No LLM is called; nothing is billed, counted against a trial or notified. Loading an existing demo changes nothing. Requires demo:manage (member and up). Returns the GET shape and records a demo.loaded audit event.

In the dashboard: Overview → Getting started, or the empty Findings page.

Response 200 (application/json)

{
"available": true,
"loaded": true,
"agent_scan_enabled": true
}
FieldTypeRequiredDescription
availablebooleanyesSome pack enabled for this organization ships a demo sample.
loadedbooleanyesThe organization’s demo changeset exists.
agent_scan_enabledbooleanyesAgent-manipulation detection is on for this deployment. When it is off, a loaded demo holds the pack’s findings only.
  • 409 — No installed pack ships a demo sample

Remove the demo analysis

Deletes the demo changeset, its resources and their findings, including triage. A resource another changeset also holds is kept. Requires demo:manage. Returns the GET shape and records a demo.removed audit event when something was removed.

Response 200 (application/json)

{
"available": true,
"loaded": true,
"agent_scan_enabled": true
}
FieldTypeRequiredDescription
availablebooleanyesSome pack enabled for this organization ships a demo sample.
loadedbooleanyesThe organization’s demo changeset exists.
agent_scan_enabledbooleanyesAgent-manipulation detection is on for this deployment. When it is off, a loaded demo holds the pack’s findings only.

Security rules an org adds to one or more packs’ built-in rulesets. Every enabled rule targeting a pack is appended after that pack’s built-in rules whenever GET /{pack}/rules is fetched or a claim resolves rules, grouped by category. A new org gets every registered pack’s built-in rules imported as enabled rows (is_builtin_seed: true).

rule_id is a slug of title at creation and never changes, even when title is edited: findings and triage records reference it, and re-slugging would orphan them.

List custom rules for this org

The org’s custom rules. Any member. Filter by pack, category, rule type or enabled state. repository (provider/external_id), team_id and product_id keep the rules that apply there: the org-wide ones and the ones scoped to it. For a repository, that includes rules scoped to its teams and its product.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Query parameters

NameTypeRequiredDescription
packstring | nullno
categorystring | nullno
rule_typestring | nullno
enabledboolean | nullno
repositorystring | nullnoprovider/external_id
team_idstring | nullno
product_idstring | nullno

Response 200 (application/json)

{
"rules": [
{
"rule_id": "string",
"org_id": "string",
"title": "string",
"description": "string",
"category": "string",
"severity": "CRITICAL",
"packs": [
"string"
],
"rule_type": "string",
"enabled": true,
"requires_review": false,
"scope": {
"team_ids": [
"string"
],
"repositories": [
{
"provider": "github",
"external_id": "string"
}
],
"product_ids": [
"string"
]
},
"is_builtin_seed": false,
"origin": {
"kind": "adr",
"repository": {
"provider": "github",
"external_id": "string"
},
"path": "string",
"commit_sha": "string",
"blob_sha": "string",
"excerpt": "string"
},
"builtin_id": "string",
"pack_update": {
"rule_type": "aws",
"title": "string",
"severity": "CRITICAL",
"category": "string",
"description": "string"
},
"created_by": "string",
"created_at": "string",
"updated_at": "string"
}
]
}
  • 404 — Not Found

Create a custom security rule

Creates a custom rule. Requires the org’s admin role. rule_id is a slug of title and never changes afterwards. category must be a category_id this org owns. An enabled rule is added to every pack in packs the next time GET /{pack}/rules is fetched.

requires_review: true starts every match as needs_review instead of open, whatever the LLM’s confidence: for judgment calls rather than a deterministic pass or fail.

scope limits the rule to pull requests whose repository is owned by one of the team_ids, is listed in repositories, or is in one of the product_ids; null runs it on every analysis. A scoped rule never runs on an analysis that names no repository, and a team, repository or product deleted later stays in the scope and matches nothing: the rule is never widened to the whole org.

In the dashboard: Rules → Rules.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"title": "string",
"description": "string",
"category": "string",
"severity": "CRITICAL",
"packs": [
"string"
],
"rule_type": "string",
"enabled": true,
"scope": {
"team_ids": [
"string"
],
"repositories": [
{
"provider": "github",
"external_id": "string"
}
],
"product_ids": [
"string"
]
},
"requires_review": false
}
FieldTypeRequiredDescription
titlestringyes
descriptionstringyesMarkdown detection guidance fed to the LLM
categorystringyesA category_id owned by this org (see RuleCategory)
severitySeverityLevelyes
packsstring[]yesPack names this rule applies to
rule_typestring | nullnoScopes this rule to one pack variant (e.g. ‘aws’); None applies to every variant
enabledbooleanno
scopeRuleScope | nullnoWhere the rule applies; null for the whole org
requires_reviewbooleannoA match on this rule always starts life as needs_review (see FindingStatus) instead of open, regardless of the LLM’s reported confidence — for rules that are inherently a judgment call (e.g. ‘is this the right module for this use case’) rather than a deterministic pass/fail.

Response 201 (application/json)

{
"rule_id": "string",
"org_id": "string",
"title": "string",
"description": "string",
"category": "string",
"severity": "CRITICAL",
"packs": [
"string"
],
"rule_type": "string",
"enabled": true,
"requires_review": false,
"scope": {
"team_ids": [
"string"
],
"repositories": [
{
"provider": "github",
"external_id": "string"
}
],
"product_ids": [
"string"
]
},
"is_builtin_seed": false,
"origin": {
"kind": "adr",
"repository": {
"provider": "github",
"external_id": "string"
},
"path": "string",
"commit_sha": "string",
"blob_sha": "string",
"excerpt": "string"
},
"builtin_id": "string",
"pack_update": {
"rule_type": "aws",
"title": "string",
"severity": "CRITICAL",
"category": "string",
"description": "string"
},
"created_by": "string",
"created_at": "string",
"updated_at": "string"
}
FieldTypeRequiredDescription
rule_idstringyes
org_idstringyes
titlestringyes
descriptionstringyes
categorystringyes
severitySeverityLevelyes
packsstring[]yes
rule_typestring | nullno
enabledbooleanyes
requires_reviewbooleanno
scopeRuleScope | nullno
is_builtin_seedbooleannoTrue for a rule imported from a pack’s built-in ruleset at org setup (dashboard badge). Seeded rows default to enabled=True. A seeded row replaces its rule in the pack file, enabled or not: disabling it removes the rule from the ruleset, and the file’s wording never comes back.
originRuleOrigin | nullnoThe repository file this rule was drawn from; null for a rule a person wrote
builtin_idstring | nullnoFor a seeded rule: its id in the pack file (TFSEC-020); null for a rule the org wrote
pack_updatePackRuleVariant | nullnoFor a seeded rule the org edited: the pack file’s new wording, set when the file changed the rule after the org’s edit. POST …/rules/{rule_id}/reset takes it.
created_bystring | nullyes
created_atstringyes
updated_atstring | nullno
  • 404 — A packs entry is not a registered pack

Get one custom rule

One custom rule. Any member.

Path parameters

NameTypeRequiredDescription
rule_idstringyes
org_idstringyes

Response 200 (application/json)

{
"rule_id": "string",
"org_id": "string",
"title": "string",
"description": "string",
"category": "string",
"severity": "CRITICAL",
"packs": [
"string"
],
"rule_type": "string",
"enabled": true,
"requires_review": false,
"scope": {
"team_ids": [
"string"
],
"repositories": [
{
"provider": "github",
"external_id": "string"
}
],
"product_ids": [
"string"
]
},
"is_builtin_seed": false,
"origin": {
"kind": "adr",
"repository": {
"provider": "github",
"external_id": "string"
},
"path": "string",
"commit_sha": "string",
"blob_sha": "string",
"excerpt": "string"
},
"builtin_id": "string",
"pack_update": {
"rule_type": "aws",
"title": "string",
"severity": "CRITICAL",
"category": "string",
"description": "string"
},
"created_by": "string",
"created_at": "string",
"updated_at": "string"
}
FieldTypeRequiredDescription
rule_idstringyes
org_idstringyes
titlestringyes
descriptionstringyes
categorystringyes
severitySeverityLevelyes
packsstring[]yes
rule_typestring | nullno
enabledbooleanyes
requires_reviewbooleanno
scopeRuleScope | nullno
is_builtin_seedbooleannoTrue for a rule imported from a pack’s built-in ruleset at org setup (dashboard badge). Seeded rows default to enabled=True. A seeded row replaces its rule in the pack file, enabled or not: disabling it removes the rule from the ruleset, and the file’s wording never comes back.
originRuleOrigin | nullnoThe repository file this rule was drawn from; null for a rule a person wrote
builtin_idstring | nullnoFor a seeded rule: its id in the pack file (TFSEC-020); null for a rule the org wrote
pack_updatePackRuleVariant | nullnoFor a seeded rule the org edited: the pack file’s new wording, set when the file changed the rule after the org’s edit. POST …/rules/{rule_id}/reset takes it.
created_bystring | nullyes
created_atstringyes
updated_atstring | nullno
  • 404 — Rule not found

Update a custom rule

Partial update: only fields in the body change. Requires the org’s admin role. rule_id never changes, even when title does.

Path parameters

NameTypeRequiredDescription
rule_idstringyes
org_idstringyes

Request body (application/json)

{
"title": "string",
"description": "string",
"category": "string",
"severity": "CRITICAL",
"packs": [
"string"
],
"rule_type": "string",
"enabled": true,
"requires_review": true,
"scope": {
"team_ids": [
"string"
],
"repositories": [
{
"provider": "github",
"external_id": "string"
}
],
"product_ids": [
"string"
]
}
}
FieldTypeRequiredDescription
titlestring | nullno
descriptionstring | nullno
categorystring | nullno
severitySeverityLevel | nullno
packsstring[] | nullno
rule_typestring | nullno
enabledboolean | nullno
requires_reviewboolean | nullno
scopeRuleScope | nullnoSend null to make the rule org-wide again

Response 200 (application/json)

{
"rule_id": "string",
"org_id": "string",
"title": "string",
"description": "string",
"category": "string",
"severity": "CRITICAL",
"packs": [
"string"
],
"rule_type": "string",
"enabled": true,
"requires_review": false,
"scope": {
"team_ids": [
"string"
],
"repositories": [
{
"provider": "github",
"external_id": "string"
}
],
"product_ids": [
"string"
]
},
"is_builtin_seed": false,
"origin": {
"kind": "adr",
"repository": {
"provider": "github",
"external_id": "string"
},
"path": "string",
"commit_sha": "string",
"blob_sha": "string",
"excerpt": "string"
},
"builtin_id": "string",
"pack_update": {
"rule_type": "aws",
"title": "string",
"severity": "CRITICAL",
"category": "string",
"description": "string"
},
"created_by": "string",
"created_at": "string",
"updated_at": "string"
}
FieldTypeRequiredDescription
rule_idstringyes
org_idstringyes
titlestringyes
descriptionstringyes
categorystringyes
severitySeverityLevelyes
packsstring[]yes
rule_typestring | nullno
enabledbooleanyes
requires_reviewbooleanno
scopeRuleScope | nullno
is_builtin_seedbooleannoTrue for a rule imported from a pack’s built-in ruleset at org setup (dashboard badge). Seeded rows default to enabled=True. A seeded row replaces its rule in the pack file, enabled or not: disabling it removes the rule from the ruleset, and the file’s wording never comes back.
originRuleOrigin | nullnoThe repository file this rule was drawn from; null for a rule a person wrote
builtin_idstring | nullnoFor a seeded rule: its id in the pack file (TFSEC-020); null for a rule the org wrote
pack_updatePackRuleVariant | nullnoFor a seeded rule the org edited: the pack file’s new wording, set when the file changed the rule after the org’s edit. POST …/rules/{rule_id}/reset takes it.
created_bystring | nullyes
created_atstringyes
updated_atstring | nullno
  • 404 — Rule not found

Delete a custom rule

Deletes a custom rule. Requires the org’s admin role.

Path parameters

NameTypeRequiredDescription
rule_idstringyes
org_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 404 — Rule not found

GET /v1/orgs/{org_id}/rules/{rule_id}/coverage

Section titled “GET /v1/orgs/{org_id}/rules/{rule_id}/coverage”

Where a custom rule runs

For every repository of the org, whether a pull request there runs this rule, and the first reason it does not: rule_disabled, pack_off (none of its packs runs there), other_variant (its packs use another rule variant there), out_of_scope or excluded. without_repository gives the same answer for an analysis that names no repository. The review job uses the same function. Any member.

Path parameters

NameTypeRequiredDescription
rule_idstringyes
org_idstringyes

Response 200 (application/json)

{
"rule_id": "string",
"runs_on": 0,
"repositories": [
{
"provider": "string",
"external_id": "string",
"full_name": "string",
"reason": "runs"
}
],
"without_repository": "runs"
}
FieldTypeRequiredDescription
rule_idstringyes
runs_onintegeryesHow many repositories the rule runs on
repositoriesRepositoryRuleDecision[]yesEvery repository not removed, by full_name
without_repositoryRuleReasonyesWhether a rule runs on a target, or the first check it fails (services/rules/scope.py, rule_decision). The checks run in this order.
  • 404 — Rule not found

POST /v1/orgs/{org_id}/rules/{rule_id}/reset

Section titled “POST /v1/orgs/{org_id}/rules/{rule_id}/reset”

Take the pack’s wording for a built-in rule

For a rule seeded from a pack file: its title, description, category and severity revert to the file’s wording, and pack_update is cleared. enabled, scope, packs and requires_review stay as the org set them. An enabled rule then follows the pack file again; a disabled one stays as the org set it, so a later sync never enables it.

Path parameters

NameTypeRequiredDescription
rule_idstringyes
org_idstringyes

Response 200 (application/json)

{
"rule_id": "string",
"org_id": "string",
"title": "string",
"description": "string",
"category": "string",
"severity": "CRITICAL",
"packs": [
"string"
],
"rule_type": "string",
"enabled": true,
"requires_review": false,
"scope": {
"team_ids": [
"string"
],
"repositories": [
{
"provider": "github",
"external_id": "string"
}
],
"product_ids": [
"string"
]
},
"is_builtin_seed": false,
"origin": {
"kind": "adr",
"repository": {
"provider": "github",
"external_id": "string"
},
"path": "string",
"commit_sha": "string",
"blob_sha": "string",
"excerpt": "string"
},
"builtin_id": "string",
"pack_update": {
"rule_type": "aws",
"title": "string",
"severity": "CRITICAL",
"category": "string",
"description": "string"
},
"created_by": "string",
"created_at": "string",
"updated_at": "string"
}
FieldTypeRequiredDescription
rule_idstringyes
org_idstringyes
titlestringyes
descriptionstringyes
categorystringyes
severitySeverityLevelyes
packsstring[]yes
rule_typestring | nullno
enabledbooleanyes
requires_reviewbooleanno
scopeRuleScope | nullno
is_builtin_seedbooleannoTrue for a rule imported from a pack’s built-in ruleset at org setup (dashboard badge). Seeded rows default to enabled=True. A seeded row replaces its rule in the pack file, enabled or not: disabling it removes the rule from the ruleset, and the file’s wording never comes back.
originRuleOrigin | nullnoThe repository file this rule was drawn from; null for a rule a person wrote
builtin_idstring | nullnoFor a seeded rule: its id in the pack file (TFSEC-020); null for a rule the org wrote
pack_updatePackRuleVariant | nullnoFor a seeded rule the org edited: the pack file’s new wording, set when the file changed the rule after the org’s edit. POST …/rules/{rule_id}/reset takes it.
created_bystring | nullyes
created_atstringyes
updated_atstring | nullno
  • 404 — Rule not found
  • 409 — The rule was not seeded from a pack, or its pack no longer defines it

Sync built-in rules into editable custom-rule rows

Brings the org’s built-in rule rows in line with every registered pack’s rule files, every variant included. Requires the org’s admin role. A rule with no row gets one, enabled. A row the org never edited takes the file’s current wording, category and severity. A row the org edited, including one it only enabled or disabled, is left as it is. An unedited row whose rule left the file is disabled. Core runs the same sync for every org at startup when the pack files change; this endpoint reruns it for one org. Once an org has an enabled rule for a pack and variant, GET /{pack}/rules shows this org’s rules for that variant instead of the built-in ones.

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

The groups custom rules are organised under: an org-owned list, not a fixed enum. Every category, including the seeded defaults, can be renamed or deleted. Deleting one that rules still reference is not blocked: GET /{pack}/rules lists those rules under “Uncategorized”. A new org gets the defaults seeded before its custom rules, which reference them.

List rule categories for this org

The org’s rule categories. Any member.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"categories": [
{
"category_id": "string",
"org_id": "string",
"name": "string",
"is_builtin_seed": false,
"created_by": "string",
"created_at": "string",
"updated_at": "string"
}
]
}

Create a rule category

Creates a rule category. Requires the org’s admin role. category_id is a slug of name and never changes afterwards, since custom rules reference it.

In the dashboard: Rules → Rule Categories.

Path parameters

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"name": "string"
}

Response 201 (application/json)

{
"category_id": "string",
"org_id": "string",
"name": "string",
"is_builtin_seed": false,
"created_by": "string",
"created_at": "string",
"updated_at": "string"
}
FieldTypeRequiredDescription
category_idstringyes
org_idstringyes
namestringyes
is_builtin_seedbooleannoTrue for one of the default categories seeded at org setup (dashboard badge). Fully editable/deletable like any other category — this is informational only.
created_bystring | nullyes
created_atstringyes
updated_atstring | nullno

GET /v1/orgs/{org_id}/rule-categories/{category_id}

Section titled “GET /v1/orgs/{org_id}/rule-categories/{category_id}”

Get one rule category

One rule category. Any member.

Path parameters

NameTypeRequiredDescription
category_idstringyes
org_idstringyes

Response 200 (application/json)

{
"category_id": "string",
"org_id": "string",
"name": "string",
"is_builtin_seed": false,
"created_by": "string",
"created_at": "string",
"updated_at": "string"
}
FieldTypeRequiredDescription
category_idstringyes
org_idstringyes
namestringyes
is_builtin_seedbooleannoTrue for one of the default categories seeded at org setup (dashboard badge). Fully editable/deletable like any other category — this is informational only.
created_bystring | nullyes
created_atstringyes
updated_atstring | nullno
  • 404 — Category not found

PATCH /v1/orgs/{org_id}/rule-categories/{category_id}

Section titled “PATCH /v1/orgs/{org_id}/rule-categories/{category_id}”

Rename a rule category

Renames a category. Requires the org’s admin role. category_id never changes, even when name does.

Path parameters

NameTypeRequiredDescription
category_idstringyes
org_idstringyes

Request body (application/json)

{
"name": "string"
}

Response 200 (application/json)

{
"category_id": "string",
"org_id": "string",
"name": "string",
"is_builtin_seed": false,
"created_by": "string",
"created_at": "string",
"updated_at": "string"
}
FieldTypeRequiredDescription
category_idstringyes
org_idstringyes
namestringyes
is_builtin_seedbooleannoTrue for one of the default categories seeded at org setup (dashboard badge). Fully editable/deletable like any other category — this is informational only.
created_bystring | nullyes
created_atstringyes
updated_atstring | nullno
  • 404 — Category not found

DELETE /v1/orgs/{org_id}/rule-categories/{category_id}

Section titled “DELETE /v1/orgs/{org_id}/rule-categories/{category_id}”

Delete a rule category

Deletes a category. Requires the org’s admin role. Not blocked by rules that still use it: GET /{pack}/rules lists them under “Uncategorized”.

Path parameters

NameTypeRequiredDescription
category_idstringyes
org_idstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 404 — Category not found

POST /v1/orgs/{org_id}/rule-categories/seed-defaults

Section titled “POST /v1/orgs/{org_id}/rule-categories/seed-defaults”

(Re-)import the default rule categories

(Re-)imports the default categories. Requires the org’s admin role. Idempotent: skips any category_id the org already has.

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