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.
GET /v1/packs
Section titled “GET /v1/packs”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
| Name | Type | Required | Description |
|---|---|---|---|
repository | string | null | no | provider/external_id: list the packs that run on this repository |
all | boolean | no | Also list the packs that are off |
Response 200 (application/json)
{ "packs": [ { "name": "terraform-plan", "description": "Analyses terraform plan output…" } ]}GET /v1/{pack_name}/rules
Section titled “GET /v1/{pack_name}/rules”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
| Name | Type | Required | Description |
|---|---|---|---|
pack_name | string | yes | Pack name |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
rule_type | string | null | no | Rule sub-category filter |
repository | string | null | no | provider/external_id of the repository this comes from: its rule variants, scoped rules, exclusions and enabled packs apply |
200404— Pack not found, no rule file for that type, or the repository is not listed501— The pack does not support rules yet
GET /v1/{pack_name}/rules/{rule_id}
Section titled “GET /v1/{pack_name}/rules/{rule_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
pack_name | string | yes | Pack name |
rule_id | string | yes | Built-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" } ]}| Field | Type | Required | Description |
|---|---|---|---|
pack | string | yes | |
rule_id | string | yes | |
variants | PackRuleVariant[] | yes | One entry per rule file that defines the rule, with the default variant first. |
404— Pack not found, or no rule file of the pack definesrule_id
POST /v1/{pack_name}/{changeset}/ingest
Section titled “POST /v1/{pack_name}/{changeset}/ingest”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 batchGET /changesets/{changeset}/report → the reportThe 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
| Name | Type | Required | Description |
|---|---|---|---|
pack_name | string | yes | Pack name |
changeset | string | yes | Logical grouping for this analysis run |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
repository | string | null | no | provider/external_id of the repository this comes from: its rule variants, scoped rules, exclusions and enabled packs apply |
rule_type | string | null | no | Rule variant for this pack’s units (e.g. aws); the repository’s or the pack’s default when omitted |
revision | string | null | no | Add 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" } ]}| Field | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | |
revision_id | string | yes | The revision the units landed in. Pass it to claims, report and gate |
unit_count | integer | yes | Units this call parsed |
pending_count | integer | yes | Units of the revision with no analysis yet, all ingests included |
units | UnitSummary[] | 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" } ]}| Field | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | |
revision_id | string | yes | The revision the units landed in. Pass it to claims, report and gate |
unit_count | integer | yes | Units this call parsed |
pending_count | integer | yes | Units of the revision with no analysis yet, all ingests included |
units | UnitSummary[] | yes |
404— Unknown pack, the repository is not listed, or the pack is not enabled here409—revisionis not the current one, or was ingested for another repository413— Input overserver.max_input_size_mb501— The pack does not support ingestion
POST /v1/{pack_name}/{changeset}/analyze
Section titled “POST /v1/{pack_name}/{changeset}/analyze”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
| Name | Type | Required | Description |
|---|---|---|---|
pack_name | string | yes | Pack name |
changeset | string | yes | Logical 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" }}| Field | Type | Required | Description |
|---|---|---|---|
connection_id | string | yes | The 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. |
model | string | yes | Provider-specific model name, e.g. ‘claude-sonnet-5’ |
api_key | string | null | no | LLM 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_input | string | yes | Raw pack input text, same as POST …/ingest |
rule_type | string | null | no | Rule sub-category filter, e.g. ‘aws’ |
categories | string[] | null | no | Rule 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. |
repository | RepositoryKey | null | no | The 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": [ {} ]}| Field | Type | Required | Description |
|---|---|---|---|
job_id | string | yes | The 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_id | string | yes | The revision of the changeset this run ingested. |
report_markdown | string | yes | |
resource_count | integer | yes | |
quota_exceeded | boolean | no | True if the org’s monthly LLM budget was hit mid-run — the report is partial. |
packs_used | string[] | no | Packs actually invoked. Empty for the explicit-pack /analyze endpoint (the caller already knows); populated for /analyze/auto. |
detections | object[] | no | Auto-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"}| Field | Type | Required | Description |
|---|---|---|---|
job_id | string | yes | |
status | string | yes | |
revision_id | string | yes | The revision of the changeset this job analyses. |
400— Noapi_keygiven and none on the connection, or(provider kind, model)is not on the allowed-models catalog402— The org’s monthly spend cap is already reached, or the org is not entitled; checked before any work starts404— Unknown pack, the pack is not enabled here, or the repository is not listed413— Input overserver.max_input_size_mb501— The pack does not support ingestion502— The LLM’s output could not be parsed, or it stopped atanalysis.llm_max_output_tokens(sync path only; the async path records it on the job). The body carriesjob_id
POST /v1/{changeset}/ingest/auto
Section titled “POST /v1/{changeset}/ingest/auto”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
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Logical grouping for this analysis run |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
repository | string | null | no | provider/external_id of the repository this comes from: its rule variants, scoped rules, exclusions and enabled packs apply |
revision | string | null | no | Add 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 } ]}200409—revisionis not the changeset’s current revision, or names another repository413— Input overserver.max_input_size_mb
POST /v1/{changeset}/analyze/auto
Section titled “POST /v1/{changeset}/analyze/auto”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
| Name | Type | Required | Description |
|---|---|---|---|
changeset | string | yes | Logical 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" }}| Field | Type | Required | Description |
|---|---|---|---|
connection_id | string | yes | The 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. |
model | string | yes | Provider-specific model name, e.g. ‘claude-sonnet-5’ |
api_key | string | null | no | LLM 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_input | string | yes | Raw pack input text, same as POST …/ingest |
rule_type | string | null | no | Rule sub-category filter, e.g. ‘aws’ |
categories | string[] | null | no | Rule 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. |
repository | RepositoryKey | null | no | The 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": [ {} ]}| Field | Type | Required | Description |
|---|---|---|---|
job_id | string | yes | The 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_id | string | yes | The revision of the changeset this run ingested. |
report_markdown | string | yes | |
resource_count | integer | yes | |
quota_exceeded | boolean | no | True if the org’s monthly LLM budget was hit mid-run — the report is partial. |
packs_used | string[] | no | Packs actually invoked. Empty for the explicit-pack /analyze endpoint (the caller already knows); populated for /analyze/auto. |
detections | object[] | no | Auto-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"}| Field | Type | Required | Description |
|---|---|---|---|
job_id | string | yes | |
status | string | yes | |
revision_id | string | yes | The revision of the changeset this job analyses. |
400— Noapi_keygiven and none on the connection, or(provider kind, model)is not on the allowed-models catalog402— The org’s monthly spend cap is already reached, or the org is not entitled; checked before any work starts502— The LLM’s output could not be parsed, or it stopped atanalysis.llm_max_output_tokens(sync path only; the async path records it on the job). The body carriesjob_id
GET /v1/orgs/{org_id}/packs
Section titled “GET /v1/orgs/{org_id}/packs”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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 } ]}POST /v1/orgs/{org_id}/packs/{pack_name}
Section titled “POST /v1/orgs/{org_id}/packs/{pack_name}”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
pack_name | string | yes |
Request body (application/json)
{ "enabled": true}Response 200 (application/json)
{ "pack_name": "terraform-code-change", "enabled": false}404—pack_nameis 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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
pack_name | string | yes |
200404—pack_nameis not a registered pack
Analysis jobs
Section titled “Analysis jobs”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.
GET /v1/jobs
Section titled “GET /v1/jobs”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
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | no | queued|running|done|failed|cancelled |
limit | integer | no | |
offset | integer | no |
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 /v1/jobs/{job_id}
Section titled “GET /v1/jobs/{job_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
job_id | string | yes | Job 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}| Field | Type | Required | Description |
|---|---|---|---|
job_id | string | yes | |
org_id | string | yes | |
mode | "sync" | "async" | yes | |
status | "queued" | "running" | "done" | "failed" | "cancelled" | yes | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | null | no | Stamped 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_at | string (date-time) | null | no | |
processed_count | integer | null | no | Units of work completed so far. |
total_count | integer | null | no | Total units this run will process — set alongside the first progress update. |
retry_of | string | null | no | job_id of the original job this run resumed, if it was created as a retry. |
error | string | null | no | |
trigger | "api" | "scm_webhook" | "repository_scan" | no | |
kind | string | null | no | The queued job kind a worker runs it as; null for a job run in the replica that accepted it. |
attempts | integer | null | no | How many times a worker has claimed it — above 1 when a worker died mid-run. |
request_id | string | null | no | X-Request-ID of the request that created the job. The job’s log lines carry it too. |
external_ref | object | null | no | Provider-specific origin, e.g. {‘provider’: ‘example’, ‘id’: ‘42’} |
changeset | string | yes | |
revision_id | string | yes | The revision of changeset this job ingested and analyses. A retry resumes the same revision, even after the changeset has moved on. |
pack | string | yes | Pack 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_backend | string | null | yes | Provider kind this run called. Null for a client-led repository scan, which calls none. |
connection_id | string | null | no | The 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. |
model | string | null | yes | The model this run called. Null for a client-led repository scan. |
rule_type | string | null | no | |
repository | RepositoryKey | null | no | The repository the run was scoped to, if any |
packs_used | string[] | no | Populated only when pack == ‘auto’. |
detections | object[] | no | Auto-routing audit trail — see AnalyzeResponse.detections. Populated only when pack == ‘auto’. |
injection_detections | object[] | no | Agent-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_scoring | InjectionScoring | null | no | What 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_count | integer | null | no | |
calibration_snapshot_id | string | null | no | Content 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_resource | object | null | no | hash/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_exceeded | boolean | no |
404— Unknown job, or it belongs to another org
POST /v1/jobs/{job_id}/cancel
Section titled “POST /v1/jobs/{job_id}/cancel”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
| Name | Type | Required | Description |
|---|---|---|---|
job_id | string | yes | job_id of the queued/running job to cancel |
Response 200 (application/json)
{ "job_id": "string", "status": "cancelled", "was": "queued"}| Field | Type | Required | Description |
|---|---|---|---|
job_id | string | yes | |
status | string | yes | |
was | "queued" | "running" | yes | The 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 org409— The job already finished (done,failed,cancelled), or it is amode: "sync"job, which lives inside its request and has nothing left to stop
POST /v1/jobs/{job_id}/retry
Section titled “POST /v1/jobs/{job_id}/retry”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
| Name | Type | Required | Description |
|---|---|---|---|
job_id | string | yes | job_id of the failed job to retry |
Request body (application/json, optional)
{ "api_key": "string"}| Field | Type | Required | Description |
|---|---|---|---|
api_key | string | null | no | LLM 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"}| Field | Type | Required | Description |
|---|---|---|---|
job_id | string | yes | |
status | string | yes | |
retry_of | string | yes | job_id of the original failed job this run resumes. |
200400— Noapi_keygiven and none on the connection, or(provider kind, model)is not on the allowed-models catalog402— The org’s monthly spend cap is already reached, or the org is not entitled404— Unknown job, or it belongs to another org409— Nothing left to analyse (a plaindone, or stillqueuedorrunning), or a code-host webhook job
Demo analysis
Section titled “Demo analysis”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.
GET /v1/demo
Section titled “GET /v1/demo”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}| Field | Type | Required | Description |
|---|---|---|---|
available | boolean | yes | Some pack enabled for this organization ships a demo sample. |
loaded | boolean | yes | The organization’s demo changeset exists. |
agent_scan_enabled | boolean | yes | Agent-manipulation detection is on for this deployment. When it is off, a loaded demo holds the pack’s findings only. |
POST /v1/demo
Section titled “POST /v1/demo”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}| Field | Type | Required | Description |
|---|---|---|---|
available | boolean | yes | Some pack enabled for this organization ships a demo sample. |
loaded | boolean | yes | The organization’s demo changeset exists. |
agent_scan_enabled | boolean | yes | Agent-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
DELETE /v1/demo
Section titled “DELETE /v1/demo”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}| Field | Type | Required | Description |
|---|---|---|---|
available | boolean | yes | Some pack enabled for this organization ships a demo sample. |
loaded | boolean | yes | The organization’s demo changeset exists. |
agent_scan_enabled | boolean | yes | Agent-manipulation detection is on for this deployment. When it is off, a loaded demo holds the pack’s findings only. |
Custom rules
Section titled “Custom rules”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.
GET /v1/orgs/{org_id}/rules
Section titled “GET /v1/orgs/{org_id}/rules”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
pack | string | null | no | |
category | string | null | no | |
rule_type | string | null | no | |
enabled | boolean | null | no | |
repository | string | null | no | provider/external_id |
team_id | string | null | no | |
product_id | string | null | no |
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
POST /v1/orgs/{org_id}/rules
Section titled “POST /v1/orgs/{org_id}/rules”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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}| Field | Type | Required | Description |
|---|---|---|---|
title | string | yes | |
description | string | yes | Markdown detection guidance fed to the LLM |
category | string | yes | A category_id owned by this org (see RuleCategory) |
severity | SeverityLevel | yes | |
packs | string[] | yes | Pack names this rule applies to |
rule_type | string | null | no | Scopes this rule to one pack variant (e.g. ‘aws’); None applies to every variant |
enabled | boolean | no | |
scope | RuleScope | null | no | Where the rule applies; null for the whole org |
requires_review | boolean | no | A 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"}| Field | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
org_id | string | yes | |
title | string | yes | |
description | string | yes | |
category | string | yes | |
severity | SeverityLevel | yes | |
packs | string[] | yes | |
rule_type | string | null | no | |
enabled | boolean | yes | |
requires_review | boolean | no | |
scope | RuleScope | null | no | |
is_builtin_seed | boolean | no | True 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. |
origin | RuleOrigin | null | no | The repository file this rule was drawn from; null for a rule a person wrote |
builtin_id | string | null | no | For a seeded rule: its id in the pack file (TFSEC-020); null for a rule the org wrote |
pack_update | PackRuleVariant | null | no | For 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_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
404— Apacksentry is not a registered pack
GET /v1/orgs/{org_id}/rules/{rule_id}
Section titled “GET /v1/orgs/{org_id}/rules/{rule_id}”Get one custom rule
One custom rule. Any member.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
org_id | string | yes |
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"}| Field | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
org_id | string | yes | |
title | string | yes | |
description | string | yes | |
category | string | yes | |
severity | SeverityLevel | yes | |
packs | string[] | yes | |
rule_type | string | null | no | |
enabled | boolean | yes | |
requires_review | boolean | no | |
scope | RuleScope | null | no | |
is_builtin_seed | boolean | no | True 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. |
origin | RuleOrigin | null | no | The repository file this rule was drawn from; null for a rule a person wrote |
builtin_id | string | null | no | For a seeded rule: its id in the pack file (TFSEC-020); null for a rule the org wrote |
pack_update | PackRuleVariant | null | no | For 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_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
404— Rule not found
PATCH /v1/orgs/{org_id}/rules/{rule_id}
Section titled “PATCH /v1/orgs/{org_id}/rules/{rule_id}”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
| Name | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
org_id | string | yes |
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" ] }}| Field | Type | Required | Description |
|---|---|---|---|
title | string | null | no | |
description | string | null | no | |
category | string | null | no | |
severity | SeverityLevel | null | no | |
packs | string[] | null | no | |
rule_type | string | null | no | |
enabled | boolean | null | no | |
requires_review | boolean | null | no | |
scope | RuleScope | null | no | Send 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"}| Field | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
org_id | string | yes | |
title | string | yes | |
description | string | yes | |
category | string | yes | |
severity | SeverityLevel | yes | |
packs | string[] | yes | |
rule_type | string | null | no | |
enabled | boolean | yes | |
requires_review | boolean | no | |
scope | RuleScope | null | no | |
is_builtin_seed | boolean | no | True 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. |
origin | RuleOrigin | null | no | The repository file this rule was drawn from; null for a rule a person wrote |
builtin_id | string | null | no | For a seeded rule: its id in the pack file (TFSEC-020); null for a rule the org wrote |
pack_update | PackRuleVariant | null | no | For 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_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
404— Rule not found
DELETE /v1/orgs/{org_id}/rules/{rule_id}
Section titled “DELETE /v1/orgs/{org_id}/rules/{rule_id}”Delete a custom rule
Deletes a custom rule. Requires the org’s admin role.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
org_id | string | yes |
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
| Name | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "rule_id": "string", "runs_on": 0, "repositories": [ { "provider": "string", "external_id": "string", "full_name": "string", "reason": "runs" } ], "without_repository": "runs"}| Field | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
runs_on | integer | yes | How many repositories the rule runs on |
repositories | RepositoryRuleDecision[] | yes | Every repository not removed, by full_name |
without_repository | RuleReason | yes | Whether 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
| Name | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
org_id | string | yes |
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"}| Field | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
org_id | string | yes | |
title | string | yes | |
description | string | yes | |
category | string | yes | |
severity | SeverityLevel | yes | |
packs | string[] | yes | |
rule_type | string | null | no | |
enabled | boolean | yes | |
requires_review | boolean | no | |
scope | RuleScope | null | no | |
is_builtin_seed | boolean | no | True 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. |
origin | RuleOrigin | null | no | The repository file this rule was drawn from; null for a rule a person wrote |
builtin_id | string | null | no | For a seeded rule: its id in the pack file (TFSEC-020); null for a rule the org wrote |
pack_update | PackRuleVariant | null | no | For 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_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
404— Rule not found409— The rule was not seeded from a pack, or its pack no longer defines it
POST /v1/orgs/{org_id}/rules/seed-builtin
Section titled “POST /v1/orgs/{org_id}/rules/seed-builtin”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "created": 0, "updated": 0, "disabled": 0}| Field | Type | Required | Description |
|---|---|---|---|
created | integer | yes | |
updated | integer | no | Built-in rules whose wording an org never edited, brought in line with the pack file |
disabled | integer | no | Built-in rules an org never edited that left the pack file |
Rule categories
Section titled “Rule categories”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.
GET /v1/orgs/{org_id}/rule-categories
Section titled “GET /v1/orgs/{org_id}/rule-categories”List rule categories for this org
The org’s rule categories. Any member.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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" } ]}POST /v1/orgs/{org_id}/rule-categories
Section titled “POST /v1/orgs/{org_id}/rule-categories”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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
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"}| Field | Type | Required | Description |
|---|---|---|---|
category_id | string | yes | |
org_id | string | yes | |
name | string | yes | |
is_builtin_seed | boolean | no | True for one of the default categories seeded at org setup (dashboard badge). Fully editable/deletable like any other category — this is informational only. |
created_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
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
| Name | Type | Required | Description |
|---|---|---|---|
category_id | string | yes | |
org_id | string | yes |
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"}| Field | Type | Required | Description |
|---|---|---|---|
category_id | string | yes | |
org_id | string | yes | |
name | string | yes | |
is_builtin_seed | boolean | no | True for one of the default categories seeded at org setup (dashboard badge). Fully editable/deletable like any other category — this is informational only. |
created_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
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
| Name | Type | Required | Description |
|---|---|---|---|
category_id | string | yes | |
org_id | string | yes |
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"}| Field | Type | Required | Description |
|---|---|---|---|
category_id | string | yes | |
org_id | string | yes | |
name | string | yes | |
is_builtin_seed | boolean | no | True for one of the default categories seeded at org setup (dashboard badge). Fully editable/deletable like any other category — this is informational only. |
created_by | string | null | yes | |
created_at | string | yes | |
updated_at | string | null | no |
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
| Name | Type | Required | Description |
|---|---|---|---|
category_id | string | yes | |
org_id | string | yes |
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
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "created": 0, "updated": 0, "disabled": 0}| Field | Type | Required | Description |
|---|---|---|---|
created | integer | yes | |
updated | integer | no | Built-in rules whose wording an org never edited, brought in line with the pack file |
disabled | integer | no | Built-in rules an org never edited that left the pack file |