Endpoints: LLM Connections, Billing & Findings
LLM connections
Section titled “LLM connections”An LLM connection stores an endpoint for an org: a hosted provider (anthropic, openai, …) or a self-hosted, OpenAI-compatible server. Its key is encrypted at rest. Analyze calls and the code-host integrations name connections by connection_id. A hosted provider can also be called without a stored connection: send its kind as connection_id with an inline api_key.
GET /v1/orgs/{org_id}/llm-connections
Section titled “GET /v1/orgs/{org_id}/llm-connections”List this org’s LLM connections
The org’s LLM connections, never with key material or CA bundles. Any org member: a member has to pick one to run an analysis. Creating, changing and deleting them are org-admin only. custom_endpoints_enabled mirrors llm.egress.enabled: whether a platform admin permits custom addresses here.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "connections": [ { "connection_id": "anthropic", "provider_kind": "anthropic", "display_name": "anthropic", "auth_style": "bearer", "enabled": true, "has_api_key": true, "created_at": "2026-07-09T00:00:00Z" } ], "custom_endpoints_enabled": false}POST /v1/orgs/{org_id}/llm-connections
Section titled “POST /v1/orgs/{org_id}/llm-connections”Create an LLM connection
Creates a connection. Org-admin only. Secrets (api_key, tls_ca_pem) are encrypted at rest with secrets.encryption_key and never returned. A custom base_url is checked against this deployment’s egress policy before it is stored. connection_id and provider_kind cannot change afterwards: jobs and the code-host integrations refer to them.
In the dashboard: Organization → Connections → LLM.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "connection_id": "string", "provider_kind": "anthropic", "display_name": "string", "base_url": "string", "api_key": "string", "auth_style": "bearer", "auth_header": "Authorization", "extra_headers": { "key": "string" }, "tls_ca_pem": "string", "structured_output_mode": "tool_call", "enabled": true}| Field | Type | Required | Description |
|---|---|---|---|
connection_id | string | yes | This org’s own name for the endpoint, e.g. ‘prod-vllm’. Immutable — it is what analyze requests and stored job records refer to. |
provider_kind | "anthropic" | "mistral" | "openai" | "openai_compatible" | yes | Which wire protocol this endpoint speaks |
display_name | string | null | no | Human label for the dashboard. Defaults to connection_id. |
base_url | string | null | no | Endpoint root, e.g. ‘https://llm.internal.corp/v1’. Required for openai_compatible, which has no default address to fall back on. Permitted for a hosted kind too, where it means an egress proxy fronting the vendor’s own API. |
api_key | string | null | no | Stored encrypted. Optional only when auth_style is ‘none’. |
auth_style | "bearer" | "header" | "none" | no | |
auth_header | string | no | |
extra_headers | object | no | |
tls_ca_pem | string | null | no | PEM bundle for an endpoint served under a private CA. Stored encrypted alongside the key, and never returned. |
structured_output_mode | "tool_call" | "json_schema" | "json_object" | "prompt_only" | null | no | How this endpoint is made to return the analysis schema. Null lets the backend choose — right for a hosted kind, which has exactly one mechanism. For openai_compatible, null means the pessimistic default (‘prompt_only’); POST …/test reports which modes actually work. |
enabled | boolean | no |
Response 201 (application/json)
{ "connection_id": "string", "provider_kind": "string", "display_name": "string", "base_url": "string", "auth_style": "bearer", "structured_output_mode": "string", "enabled": true, "has_api_key": false, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}400— Bad Request409—connection_idalready exists in this org
PATCH /v1/orgs/{org_id}/llm-connections/{connection_id}
Section titled “PATCH /v1/orgs/{org_id}/llm-connections/{connection_id}”Update an LLM connection
Partial update. Org-admin only. Omitting api_key or tls_ca_pem keeps the stored one. connection_id and provider_kind cannot change.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
connection_id | string | yes |
Request body (application/json)
{ "display_name": "string", "base_url": "string", "api_key": "string", "auth_style": "bearer", "auth_header": "string", "extra_headers": { "key": "string" }, "tls_ca_pem": "string", "structured_output_mode": "tool_call", "enabled": true}| Field | Type | Required | Description |
|---|---|---|---|
display_name | string | null | no | |
base_url | string | null | no | |
api_key | string | null | no | Replaces the stored key. Omit to keep it. |
auth_style | "bearer" | "header" | "none" | null | no | |
auth_header | string | null | no | |
extra_headers | object | null | no | |
tls_ca_pem | string | null | no | Replaces the stored bundle. Omit to keep it. |
structured_output_mode | "tool_call" | "json_schema" | "json_object" | "prompt_only" | null | no | |
enabled | boolean | null | no |
Response 200 (application/json)
{ "connection_id": "string", "provider_kind": "string", "display_name": "string", "base_url": "string", "auth_style": "bearer", "structured_output_mode": "string", "enabled": true, "has_api_key": false, "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}400— Bad Request404— Not Found
DELETE /v1/orgs/{org_id}/llm-connections/{connection_id}
Section titled “DELETE /v1/orgs/{org_id}/llm-connections/{connection_id}”Remove an LLM connection
Removes a connection. Org-admin only.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
connection_id | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— No such connection
POST /v1/orgs/{org_id}/llm-connections/{connection_id}/test
Section titled “POST /v1/orgs/{org_id}/llm-connections/{connection_id}/test”Probe a connection with one real analysis call
Sends one tiny unit through the full path (address, auth, model, structured output) and reports what worked, including which structured-output modes the endpoint supports. Org-admin only. Billed like any call, which is why the probe is small.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes | |
connection_id | string | yes |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
model | string | yes |
Response 200 (application/json)
{ "reachable": true, "latency_ms": 0, "structured_output": false, "usage_reported": false, "error": "string"}| Field | Type | Required | Description |
|---|---|---|---|
reachable | boolean | yes | |
latency_ms | integer | null | no | |
structured_output | boolean | no | Whether the endpoint actually returned a valid analysis schema under this connection’s structured_output_mode. Reachable but false is the interesting failure: the box is up and the mode is wrong. |
usage_reported | boolean | no | Whether the endpoint reported token counts. False means cost accounting for this connection will read zero — true of several self-hosted servers, and not itself an error. |
error | string | null | no |
404— Not Found
Allowed models
Section titled “Allowed models”The platform-wide catalog of (llm_backend, model) pairs that analyze calls and the code-host integrations accept, with the prices used to cost each call. Superadmins manage it.
An empty catalog accepts any model, since providers expose no pricing API. A fresh install is not empty: curated rows are seeded at every startup, additively, never touching an existing row, so a deleted seeded row returns on the next restart. Once the catalog has a row, only catalogued and enabled models pass. openai_compatible models are never seeded: an admin adds them with prices that match the endpoint.
GET /v1/llm/status
Section titled “GET /v1/llm/status”Whether this deployment offers LLM-backed features
Whether this deployment offers LLM-backed features. Any org member. Reads llm.enabled live, so an admin turning it off with PATCH /admin/settings shows here at once. When false, every route that needs a provider call returns 501; client-led analysis, where the caller’s own agent analyses, still works.
Response 200 (application/json)
{ "enabled": true}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | yes | False means every route that needs a provider call answers 501; client-led analysis, where the caller’s own agent does the analysing, still works. |
GET /v1/models
Section titled “GET /v1/models”List enabled LLM models available to analyze/integration calls
The enabled rows of the allowed-models catalog for the dashboard’s model pickers. Any org member. GET /admin/models has the full catalog.
Response 200 (application/json)
{ "models": [ { "llm_backend": "anthropic", "model": "string", "input_price_per_1m_usd": 0, "output_price_per_1m_usd": 0, "enabled": true, "created_by": "string", "created_at": "string", "updated_at": "string" } ]}GET /v1/admin/models
Section titled “GET /v1/admin/models”List every catalogued LLM model, including disabled ones
The full catalog, including disabled rows; filter with enabled. Superadmin only.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
enabled | boolean | null | no |
Response 200 (application/json)
{ "models": [ { "llm_backend": "anthropic", "model": "string", "input_price_per_1m_usd": 0, "output_price_per_1m_usd": 0, "enabled": true, "created_by": "string", "created_at": "string", "updated_at": "string" } ]}POST /v1/admin/models
Section titled “POST /v1/admin/models”Add a model to the allowed-models catalog
Adds a model to the catalog. Superadmin only. Prices are entered by hand, since no provider exposes a pricing API; they enforce the allowlist and determine the cost of every later analyze call that uses the model.
In the dashboard: Platform Admin → Catalog → Models.
Request body (application/json)
{ "llm_backend": "anthropic", "model": "string", "input_price_per_1m_usd": 0, "output_price_per_1m_usd": 0, "enabled": true}| Field | Type | Required | Description |
|---|---|---|---|
llm_backend | "anthropic" | "mistral" | "openai" | "openai_compatible" | yes | |
model | string | yes | Provider-specific model name |
input_price_per_1m_usd | number | yes | USD per 1,000,000 input tokens |
output_price_per_1m_usd | number | yes | USD per 1,000,000 output tokens |
enabled | boolean | no |
Response 201 (application/json)
{ "llm_backend": "anthropic", "model": "string", "input_price_per_1m_usd": 0, "output_price_per_1m_usd": 0, "enabled": true, "created_by": "string", "created_at": "string", "updated_at": "string"}409—(llm_backend, model)already exists
PATCH /v1/admin/models/{llm_backend}/{model}
Section titled “PATCH /v1/admin/models/{llm_backend}/{model}”Update a catalogued model’s price or enabled flag
Partial update of a model’s prices or enabled flag. Superadmin only.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
llm_backend | string | yes | |
model | string | yes |
Request body (application/json)
{ "input_price_per_1m_usd": 0, "output_price_per_1m_usd": 0, "enabled": true}Response 200 (application/json)
{ "llm_backend": "anthropic", "model": "string", "input_price_per_1m_usd": 0, "output_price_per_1m_usd": 0, "enabled": true, "created_by": "string", "created_at": "string", "updated_at": "string"}404— Not Found
DELETE /v1/admin/models/{llm_backend}/{model}
Section titled “DELETE /v1/admin/models/{llm_backend}/{model}”Remove a model from the allowed-models catalog
Removes a model from the catalog. Superadmin only. An org still set to use it, through a saved code-host integration or a client that hardcodes it, gets 400 on its next call.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
llm_backend | string | yes | |
model | string | yes |
Response 200 (application/json)
{ "detail": "string"}404— Not Found
Quota and usage
Section titled “Quota and usage”An org’s monthly spend cap and its usage. The cap is optional and unlimited by default. There is no billing-provider integration: the platform meters usage and blocks work over the cap with 402.
Here the billed meter is resources analysed across every pack, and spend is LLM token cost. Server-side analysis checks the cap before it starts and answers 402 once it is reached.
PATCH /v1/orgs/{org_id}/quota
Section titled “PATCH /v1/orgs/{org_id}/quota”Set or clear the org’s monthly spend cap
Sets or clears the org’s monthly spend cap. Requires the org’s admin role. monthly_budget_usd: null clears it (unlimited, the default). Whatever product work costs money enforces the cap: once this month’s spend reaches it, that work is refused with 402. There is no billing-provider integration: this is internal metering and a hard block.
Set it on every enterprise org: the enterprise commitment meters the billed unit, not spend, so costs can exceed the payment with a flat fee. To test the 402 block, set the cap at or below total_cost_usd from GET /orgs/{org_id}/usage.
In the dashboard: Organization → Usage & Audit → Quota.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "monthly_budget_usd": 0}| Field | Type | Required | Description |
|---|---|---|---|
monthly_budget_usd | number | null | no | Monthly spend cap in USD. null clears the cap (unlimited). |
Response 200 (application/json)
{ "monthly_budget_usd": 50}GET /v1/orgs/{org_id}/usage
Section titled “GET /v1/orgs/{org_id}/usage”This month’s spend vs. the org’s budget, billed-meter usage and trial progress
This month’s spend against the budget, the billed meter, trial progress and the enterprise commitment. Requires the org’s viewer role.
total_cost_usdis the cost of every usage event this month.budget_usdandremaining_usdare null when there is no cap.periodis the calendar month in UTC (YYYY-MM); usage resets at its start, with no rollover.billed_quantitycounts the product’s billed meter for every org, whatever the plan; only billing is gated.metered_cost_usd: null onfree. Onpaid, the degressive per-unit price for the whole quantity, from the first unit (PATCH /admin/pricing). Onenterprise, the overage beyondincluded_units_per_monthat the cheapest tier:0.0, not null, inside the commitment.included_units_per_month,included_units_remaining,overage_unitsandcommitted_amount_usddescribe an enterprise commitment and are null or 0 on every other plan. On an enterprise contract with no ceiling,included_units_per_monthis null: unlimited, not zero.trialsis set only on a cloud deployment for a non-paying plan, one entry per meter that carries a trial (meter,unit,used,allowance,remaining).
Going over a commitment never blocks anything: a positive overage_units and a true contract_expired are reported so a person can act commercially. Neither refuses any work or locks an org; that takes PATCH /admin/organizations/{org_id}/lock or a plan change.
In the dashboard: Organization → Usage & Audit → Usage.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "period": "string", "total_cost_usd": 0, "budget_usd": 0, "remaining_usd": 0, "billed_meter": "string", "billed_unit": "string", "billed_quantity": 0, "metered_cost_usd": 0, "included_units_per_month": 0, "included_units_remaining": 0, "overage_units": 0, "committed_amount_usd": 0, "contract_expired": false, "trials": [ { "meter": "string", "unit": "string", "used": 0, "allowance": 0, "remaining": 0 } ]}| Field | Type | Required | Description |
|---|---|---|---|
period | string | yes | Calendar month this summary covers, e.g. ‘2026-07’ |
total_cost_usd | number | yes | This month’s recorded spend (the cost of every usage event). |
budget_usd | number | null | yes | |
remaining_usd | number | null | yes | |
billed_meter | string | null | no | The meter pricing applies to, or null when the product bills none. |
billed_unit | string | null | no | What one unit of billed_meter is called. |
billed_quantity | integer | no | Units of billed_meter recorded this month. Metered regardless of plan_tier — only priced (metered_cost_usd) on a paying plan. |
metered_cost_usd | number | null | no | What this month’s usage costs — null on plan_tier=‘free’, which is never billed. On ‘paid’, the degressive per-unit cost for the whole billed_quantity (controllers.services.billing.pricing.compute_metered_cost_usd). On ‘enterprise’, the overage beyond included_units_per_month only, at the volume rate (compute_overage_cost_usd) — 0.0, not null, while the org is inside its commitment. |
included_units_per_month | integer | null | no | The org’s committed monthly allowance of billed_meter (models.auth.OrgContract). Null on every tier but ‘enterprise’, and null for an enterprise org whose contract sets no ceiling — which means unlimited, not zero. |
included_units_remaining | integer | null | no | included_units_per_month minus billed_quantity, floored at 0. Null under the same conditions as included_units_per_month. |
overage_units | integer | no | Units beyond the commitment this month — what metered_cost_usd is charged on for an enterprise org. Always 0 on other tiers, where the concept doesn’t apply (a ‘paid’ org has no allowance to exceed). |
committed_amount_usd | number | null | no | The flat monthly amount the commitment costs (OrgContract.committed_amount_usd), for display beside metered_cost_usd — this codebase never charges it. Null on non-enterprise tiers. |
contract_expired | boolean | no | The contracted term’s end date has passed (OrgContract.expires_at). Advisory: an expired contract does not revoke entitlement — see OrgContract.expires_at for why. |
trials | TrialUsage[] | null | no | One entry per meter with a trial allowance. Null on a self-hosted deployment or a paying plan, where no trial applies. |
Findings
Section titled “Findings”Each finding an analysis produces gets a triage record, keyed by (resource_hash, rule_id) within the org. There is no create route: records appear whenever an analysis is submitted. Re-analysing a resource refreshes last_seen and occurrence_count and never resets a status a person set.
A new finding starts as needs_review instead of open when its rule has requires_review or when the LLM reports LOW or UNKNOWN confidence. needs_review notifies the channels subscribed to finding.needs_review and holds the pull request’s check at pending, whatever the severity.
GET /v1/findings
Section titled “GET /v1/findings”List finding records for the caller’s org
The org’s finding records, newest last_seen first, paged. Requires member. Without status, returns every status except closed. team_id gives a team’s review queue; repository (provider/external_id) gives findings seen in that repository’s changesets, and product_id gives findings seen in any of the product’s repositories as they are grouped now: a repository moved to another product takes its findings with it. has_ticket keeps the findings with, or without, a Jira issue; ticket holds the issue’s key, link and status.
closed means a later revision no longer reports the finding: a push removed or changed its code, and no other changeset’s current revision still holds it. The status is set when that revision’s analysis completes, never before. closed_in names the changeset and revision that closed it and the status it had before. A revision that brings the code back, such as a revert, reopens it with that status. A closed finding ages out after its severity’s retention window.
assigned_team_ids is set when the finding enters needs_review. It lists the teams that review the repository the pull request came from. It is empty when no team owns that repository, and for API analyses with no repository.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | string | null | no | open|needs_review|acknowledged|suppressed|false_positive|closed. Without it, closed findings are left out. |
severity | string | null | no | e.g. CRITICAL, HIGH |
rule_id | string | null | no | |
changeset | string | null | no | Only findings seen under this changeset |
team_id | string | null | no | Only findings assigned to this team |
repository | string | null | no | Only findings seen in this repository (provider/external_id) |
product_id | string | null | no | Only findings seen in this product’s repositories |
resource_hash | string | null | no | Only findings on this resource |
has_ticket | boolean | null | no | true: only findings with a Jira issue. false: only findings without one. |
limit | integer | no | |
offset | integer | no |
Response 200 (application/json)
{ "findings": [ { "resource_hash": "string", "rule_id": "string", "unit_address": "string", "severity": "string", "title": "string", "status": "open", "first_seen": "2026-01-01T00:00:00Z", "last_seen": "2026-01-01T00:00:00Z", "occurrence_count": 1, "note": "string", "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z", "changesets": [ "string" ], "assigned_team_ids": [ "string" ], "repositories": [ "string" ], "closed_in": { "changeset": "string", "revision_id": "string", "at": "2026-01-01T00:00:00Z", "status_before": "open" }, "reason_code": "false_positive", "ticket": { "key": "string", "url": "string", "synced_status": "open", "synced_changesets": [ "string" ], "closed_by_opentremor": false, "jira_status": "string", "jira_status_category": "string", "created_at": "2026-01-01T00:00:00Z", "last_error": "string" } } ], "total": 0}GET /v1/findings/summary
Section titled “GET /v1/findings/summary”Aggregated finding counts for the caller’s org
Point-in-time counts by status and severity, plus new and resolved counts over the last days days. Requires member. by_severity_open counts only open findings. resolved_in_period counts findings that moved from open to any status other than needs_review: a finding awaiting a person is not resolved just because it left open.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
days | integer | no |
Response 200 (application/json)
{ "period_days": 0, "total": 0, "by_status": { "key": 0 }, "by_severity_open": { "key": 0 }, "new_in_period": 0, "resolved_in_period": 0}| Field | Type | Required | Description |
|---|---|---|---|
period_days | integer | yes | |
total | integer | yes | All findings regardless of status |
by_status | object | yes | |
by_severity_open | object | yes | Severity breakdown of status=open findings only |
new_in_period | integer | yes | Findings first seen within the window |
resolved_in_period | integer | yes | Findings whose status left ‘open’ within the window |
PATCH /v1/findings/{resource_hash}/{rule_id}
Section titled “PATCH /v1/findings/{resource_hash}/{rule_id}”Update a finding’s triage status
Acknowledge, suppress, mark as a false positive, flag for human review (status: "needs_review"), or reopen (status: "open") one finding. The status persists across re-analysis of the same resource — a re-scan only refreshes last_seen/occurrence_count, it never resets a triaged status back to open. Setting needs_review notifies every channel of this org subscribed to finding.needs_review — the same notification a finding auto-flagged into needs_review at creation time fires.
If the finding’s resource sits in a changeset analysed for a GitHub pull request, the PR’s commit status is re-posted with the new state — triaging is what clears a check held at pending, and it takes effect without waiting for another push. Best-effort: a GitHub failure is logged, never surfaced here, since the status change itself has already been saved.
Every status that carries a verdict (acknowledged, suppressed, false_positive) is also appended to this org’s review-feedback log — what GET /rule-health aggregates, and what steers later analyses. Pass reason_code to say why: for suppressed it is the only thing distinguishing “this is wrong” from “this is right and we accept it”, and without it the verdict is recorded as unclear rather than guessed at.
closed cannot be set here (422): it is set when a completed revision no longer reports the finding. Reopen a closed finding with status: "open".
In the dashboard: Analysis → Findings, the status menu on each row.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
resource_hash | string | yes | Resource content hash |
rule_id | string | yes | Rule ID from the finding |
Request body (application/json)
{ "status": "open", "note": "string", "reason_code": "false_positive"}| Field | Type | Required | Description |
|---|---|---|---|
status | FindingStatus | yes | |
note | string | null | no | Optional triage note, e.g. why this was suppressed |
reason_code | ReasonCode | null | no | Why, as one of a fixed set — what turns this triage action into a usable learning signal (models/feedback.py). Optional, and its absence is never guessed at: a suppressed with no reason_code is recorded as an unclear verdict rather than resolved into a confirmation or a rejection. The one status where supplying it actually changes the recorded verdict is suppressed; for acknowledged and false_positive the status already says which way it points. |
Response 200 (application/json)
{ "resource_hash": "string", "rule_id": "string", "unit_address": "string", "severity": "string", "title": "string", "status": "open", "first_seen": "2026-01-01T00:00:00Z", "last_seen": "2026-01-01T00:00:00Z", "occurrence_count": 1, "note": "string", "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z", "changesets": [ "string" ], "assigned_team_ids": [ "string" ], "repositories": [ "string" ], "closed_in": { "changeset": "string", "revision_id": "string", "at": "2026-01-01T00:00:00Z", "status_before": "open" }, "reason_code": "false_positive", "ticket": { "key": "string", "url": "string", "synced_status": "open", "synced_changesets": [ "string" ], "closed_by_opentremor": false, "jira_status": "string", "jira_status_category": "string", "created_at": "2026-01-01T00:00:00Z", "last_error": "string" }}| Field | Type | Required | Description |
|---|---|---|---|
resource_hash | string | yes | |
rule_id | string | yes | |
unit_address | string | yes | |
severity | string | yes | |
title | string | yes | |
status | FindingStatus | no | |
first_seen | string (date-time) | yes | |
last_seen | string (date-time) | yes | |
occurrence_count | integer | no | |
note | string | null | no | |
updated_by | string | null | no | |
updated_at | string (date-time) | null | no | |
changesets | string[] | no | Changeset(s) this finding’s resource_hash has been seen under — usually one, but a content-addressed hash can be shared across changesets |
assigned_team_ids | string[] | no | The teams expected to review it. Set when it enters needs_review, from the repository its changeset came from; empty when no team owns that repository. |
repositories | string[] | no | The repositories (provider/external_id) it was seen in, added on every sighting. Its products are those repositories’ products, read when asked. |
closed_in | ClosedIn | null | no | Set with status closed: the revision that no longer reported it |
reason_code | ReasonCode | null | no | The reason given with the last triage status, if any |
ticket | FindingTicket | null | no | The Jira issue tracking it, if any |
404— No finding record for this(resource_hash, rule_id)pair
PUT /v1/findings/{resource_hash}/{rule_id}/teams
Section titled “PUT /v1/findings/{resource_hash}/{rule_id}/teams”Reassign a finding to other teams
Replaces assigned_team_ids. Assignment routes notifications and filters the findings list; it grants nothing — every member can still triage the finding. If the finding is in needs_review, finding.needs_review fires again for the teams that were added, so their channels hear about it. Org-wide channels receive that notification too.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
resource_hash | string | yes | Resource content hash |
rule_id | string | yes | Rule ID from the finding |
Request body (application/json)
{ "team_ids": [ "string" ]}| Field | Type | Required | Description |
|---|---|---|---|
team_ids | string[] | yes | Replaces the assigned teams. Empty unassigns. |
Response 200 (application/json)
{ "resource_hash": "string", "rule_id": "string", "unit_address": "string", "severity": "string", "title": "string", "status": "open", "first_seen": "2026-01-01T00:00:00Z", "last_seen": "2026-01-01T00:00:00Z", "occurrence_count": 1, "note": "string", "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z", "changesets": [ "string" ], "assigned_team_ids": [ "string" ], "repositories": [ "string" ], "closed_in": { "changeset": "string", "revision_id": "string", "at": "2026-01-01T00:00:00Z", "status_before": "open" }, "reason_code": "false_positive", "ticket": { "key": "string", "url": "string", "synced_status": "open", "synced_changesets": [ "string" ], "closed_by_opentremor": false, "jira_status": "string", "jira_status_category": "string", "created_at": "2026-01-01T00:00:00Z", "last_error": "string" }}| Field | Type | Required | Description |
|---|---|---|---|
resource_hash | string | yes | |
rule_id | string | yes | |
unit_address | string | yes | |
severity | string | yes | |
title | string | yes | |
status | FindingStatus | no | |
first_seen | string (date-time) | yes | |
last_seen | string (date-time) | yes | |
occurrence_count | integer | no | |
note | string | null | no | |
updated_by | string | null | no | |
updated_at | string (date-time) | null | no | |
changesets | string[] | no | Changeset(s) this finding’s resource_hash has been seen under — usually one, but a content-addressed hash can be shared across changesets |
assigned_team_ids | string[] | no | The teams expected to review it. Set when it enters needs_review, from the repository its changeset came from; empty when no team owns that repository. |
repositories | string[] | no | The repositories (provider/external_id) it was seen in, added on every sighting. Its products are those repositories’ products, read when asked. |
closed_in | ClosedIn | null | no | Set with status closed: the revision that no longer reported it |
reason_code | ReasonCode | null | no | The reason given with the last triage status, if any |
ticket | FindingTicket | null | no | The Jira issue tracking it, if any |
404— No finding record for this(resource_hash, rule_id)pair
POST /v1/findings/{resource_hash}/{rule_id}/ticket
Section titled “POST /v1/findings/{resource_hash}/{rule_id}/ticket”Create the finding’s Jira issue now
Goes to the finding’s target (a product’s, a team’s, or the default). Refused for a closed finding, a false positive, a demo finding, or one that already has an issue. A Jira error comes back as 502 and nothing is stored.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
resource_hash | string | yes | Resource content hash |
rule_id | string | yes | Rule ID from the finding |
Response 200 (application/json)
{ "resource_hash": "string", "rule_id": "string", "unit_address": "string", "severity": "string", "title": "string", "status": "open", "first_seen": "2026-01-01T00:00:00Z", "last_seen": "2026-01-01T00:00:00Z", "occurrence_count": 1, "note": "string", "updated_by": "string", "updated_at": "2026-01-01T00:00:00Z", "changesets": [ "string" ], "assigned_team_ids": [ "string" ], "repositories": [ "string" ], "closed_in": { "changeset": "string", "revision_id": "string", "at": "2026-01-01T00:00:00Z", "status_before": "open" }, "reason_code": "false_positive", "ticket": { "key": "string", "url": "string", "synced_status": "open", "synced_changesets": [ "string" ], "closed_by_opentremor": false, "jira_status": "string", "jira_status_category": "string", "created_at": "2026-01-01T00:00:00Z", "last_error": "string" }}| Field | Type | Required | Description |
|---|---|---|---|
resource_hash | string | yes | |
rule_id | string | yes | |
unit_address | string | yes | |
severity | string | yes | |
title | string | yes | |
status | FindingStatus | no | |
first_seen | string (date-time) | yes | |
last_seen | string (date-time) | yes | |
occurrence_count | integer | no | |
note | string | null | no | |
updated_by | string | null | no | |
updated_at | string (date-time) | null | no | |
changesets | string[] | no | Changeset(s) this finding’s resource_hash has been seen under — usually one, but a content-addressed hash can be shared across changesets |
assigned_team_ids | string[] | no | The teams expected to review it. Set when it enters needs_review, from the repository its changeset came from; empty when no team owns that repository. |
repositories | string[] | no | The repositories (provider/external_id) it was seen in, added on every sighting. Its products are those repositories’ products, read when asked. |
closed_in | ClosedIn | null | no | Set with status closed: the revision that no longer reported it |
reason_code | ReasonCode | null | no | The reason given with the last triage status, if any |
ticket | FindingTicket | null | no | The Jira issue tracking it, if any |
403— Forbidden404— Not Found409— Conflict502— Bad Gateway
DELETE /v1/findings/{resource_hash}/{rule_id}/ticket
Section titled “DELETE /v1/findings/{resource_hash}/{rule_id}/ticket”Unlink the finding from its Jira issue
The issue stays in Jira as it is. If a rule matches the finding, the sync may create a new issue for it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
resource_hash | string | yes | Resource content hash |
rule_id | string | yes | Rule ID from the finding |
Response 200 (application/json)
{ "detail": "string"}404— Not Found
Review feedback
Section titled “Review feedback”The append-only record of people’s verdicts on findings from dashboard triage, pull request comments and commands, and integrations, and the rule changes they suggest. Feedback from an outside contributor on a public pull request or from a comment that triggered the injection scanner is recorded as untrusted and never reaches a prompt. Nothing here changes a rule automatically.
GET /v1/feedback
Section titled “GET /v1/feedback”List this org’s review feedback
Every verdict a human has given on a finding, newest first — from dashboard triage, from an @opentremor command on a pull request, or from a review comment. Append-only: a reviewer who changes their mind produces a second entry, and both are kept.
trusted says whether an entry is allowed to influence a later analysis. Feedback from an outside contributor on a public pull request is recorded and shown like any other, and is never composed into a prompt.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
rule_id | string | null | no | |
verdict | string | null | no | confirmed|rejected|severity_wrong|missed|unclear |
source | string | null | no | dashboard_triage|pr_command|pr_review_comment|api |
resource_hash | string | null | no | |
limit | integer | no | |
offset | integer | no |
Response 200 (application/json)
{ "feedback": [ { "feedback_id": "string", "org_id": "string", "resource_hash": "string", "rule_id": "string", "changeset": "string", "severity": "string", "verdict": "confirmed", "reason_code": "false_positive", "comment": "string", "source": "dashboard_triage", "actor": "string", "trusted": true, "provenance": { "provider": "string", "repo": "string", "pr_number": 0, "comment_id": "string", "comment_url": "string", "path": "string", "line": 0, "author_role": "string" }, "created_at": "string" } ], "total": 0}POST /v1/feedback
Section titled “POST /v1/feedback”Record a review verdict
For an integration recording a human’s verdict from somewhere this server does not otherwise see — a code-review tool, a chat workflow, an internal triage queue. Triage through PATCH /findings/... records feedback by itself; this is not needed for it, and calling both would count one decision twice.
Always recorded as trusted: reaching this endpoint at all means an authenticated member of the org, which is the same bar dashboard triage clears.
Request body (application/json)
{ "resource_hash": "string", "rule_id": "string", "verdict": "confirmed", "reason_code": "false_positive", "comment": "string"}| Field | Type | Required | Description |
|---|---|---|---|
resource_hash | string | yes | |
rule_id | string | yes | |
verdict | FeedbackVerdict | yes | What a human’s signal says about a finding, normalized across every source. |
reason_code | ReasonCode | null | no | |
comment | string | null | no |
Response 201 (application/json)
{ "feedback_id": "string", "org_id": "string", "resource_hash": "string", "rule_id": "string", "changeset": "string", "severity": "string", "verdict": "confirmed", "reason_code": "false_positive", "comment": "string", "source": "dashboard_triage", "actor": "string", "trusted": true, "provenance": { "provider": "string", "repo": "string", "pr_number": 0, "comment_id": "string", "comment_url": "string", "path": "string", "line": 0, "author_role": "string" }, "created_at": "string"}| Field | Type | Required | Description |
|---|---|---|---|
feedback_id | string | yes | |
org_id | string | yes | |
resource_hash | string | null | no | None for a comment attributed to a changeset but not to one finding |
rule_id | string | null | no | None when the signal is missed or unattributable |
changeset | string | null | no | |
severity | string | null | no | The finding’s severity when the verdict was given, copied rather than joined. services/feedback/calibration.py’s severity ceiling reads it, and needs an answer even for a rule_id with no custom_rules row behind it (a built-in id an org never seeded). |
verdict | FeedbackVerdict | yes | What a human’s signal says about a finding, normalized across every source. |
reason_code | ReasonCode | null | no | |
comment | string | null | no | |
source | FeedbackSource | yes | Where the signal came from — which decides how it is trusted and attributed. |
actor | string | null | no | user_id, key_id, or GitHub login |
trusted | boolean | yes | Whether this may influence a future prompt. Decided at write time, never recomputed. |
provenance | FeedbackProvenance | no | Where a signal from a code host physically lives, so the UI can link back to it. Every field is optional: dashboard triage has none of them, a conversation comment has no path/line, and a review comment on a file the host could not map to the current diff has a path but no line. |
created_at | string | yes |
404— No finding record for this(resource_hash, rule_id)pair
GET /v1/rule-health
Section titled “GET /v1/rule-health”Per-rule reviewer precision for this org
How often reviewers confirmed what each rule raised, and how often they rejected it. precision is null until a rule has at least feedback.min_samples decisive verdicts — a ratio over one or two samples is noise, and publishing it invites acting on it.
calibrating says whether the rule currently contributes to the analysis prompt. A rule can have plenty of feedback and still not calibrate: its severity may be above feedback.severity_ceiling (CRITICAL findings are never toned down by history), or calibration may be off for this deployment entirely.
In the dashboard: Rules → Rule Health.
Response 200 (application/json)
{ "rules": [ { "rule_id": "s3-public-acl", "title": "Public bucket ACL", "severity": "HIGH", "confirmed": 2, "rejected": 7, "severity_wrong": 0, "unclear": 3, "total": 12, "precision": 0.222, "calibrating": true, "last_feedback_at": "2026-08-24T09:12:00+00:00" } ], "settings": { "calibration_enabled": true, "min_samples": 3, "severity_ceiling": "HIGH", "trusted_only": true }}GET /v1/rule-proposals
Section titled “GET /v1/rule-proposals”Rule changes suggested by review feedback or by repository files
A feedback proposal carries the exact edit suggested, the numbers behind it, and the reviewer comments it was derived from. A knowledge proposal carries the rule drawn from a repository file, such as an ADR, and the file’s own words. Nothing here is ever applied automatically.
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
status | ProposalStatus | null | no | |
source | "feedback" | "knowledge" | null | no | |
kind | "update" | "create" | "disable" | null | no | |
limit | integer | no | |
offset | integer | no |
Response 200 (application/json)
{ "proposals": [ { "proposal_id": "string", "org_id": "string", "kind": "update", "source": "feedback", "rule_id": "string", "status": "pending", "reason": "string", "changes": { "severity": "string", "requires_review": true, "enabled": true, "description_amendment": "string" }, "evidence": { "rule_id": "string", "title": "string", "severity": "string", "confirmed": 0, "rejected": 0, "severity_wrong": 0, "unclear": 0, "total": 0, "precision": 0, "calibrating": false, "last_feedback_at": "string" }, "reviewer_quotes": [ "string" ], "draft": { "title": "string", "description": "string", "category": "string", "severity": "CRITICAL", "packs": [ "string" ], "rule_type": "string", "enabled": true, "scope": { "team_ids": [ "string" ], "repositories": [ { "provider": null, "external_id": null } ], "product_ids": [ "string" ] }, "requires_review": false }, "origin": { "kind": "adr", "repository": { "provider": "github", "external_id": "string" }, "path": "string", "commit_sha": "string", "blob_sha": "string", "excerpt": "string" }, "strength": "constraint", "visibility": "unit", "created_at": "string", "decided_at": "string", "decided_by": "string" } ]}POST /v1/rule-proposals/refresh
Section titled “POST /v1/rule-proposals/refresh”Recompute rule proposals from current feedback
Requires admin role. Idempotent: a rule with an open proposal has it updated in place rather than duplicated, and an open proposal the current evidence no longer supports is withdrawn. Deterministic and cheap — no LLM call, no per-resource work — so calling it on a schedule is fine.
Response 200 (application/json)
{ "proposals": [ { "proposal_id": "string", "org_id": "string", "kind": "update", "source": "feedback", "rule_id": "string", "status": "pending", "reason": "string", "changes": { "severity": "string", "requires_review": true, "enabled": true, "description_amendment": "string" }, "evidence": { "rule_id": "string", "title": "string", "severity": "string", "confirmed": 0, "rejected": 0, "severity_wrong": 0, "unclear": 0, "total": 0, "precision": 0, "calibrating": false, "last_feedback_at": "string" }, "reviewer_quotes": [ "string" ], "draft": { "title": "string", "description": "string", "category": "string", "severity": "CRITICAL", "packs": [ "string" ], "rule_type": "string", "enabled": true, "scope": { "team_ids": [ "string" ], "repositories": [ { "provider": null, "external_id": null } ], "product_ids": [ "string" ] }, "requires_review": false }, "origin": { "kind": "adr", "repository": { "provider": "github", "external_id": "string" }, "path": "string", "commit_sha": "string", "blob_sha": "string", "excerpt": "string" }, "strength": "constraint", "visibility": "unit", "created_at": "string", "decided_at": "string", "decided_by": "string" } ]}PATCH /v1/rule-proposals/{proposal_id}
Section titled “PATCH /v1/rule-proposals/{proposal_id}”Edit the rule a knowledge proposal would create or write
Requires admin role. Replaces the proposal’s draft — the rule as it will be stored once the proposal is applied. Only for open create and update proposals drawn from a repository file; a feedback proposal is edited by passing changes to apply.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
proposal_id | string | yes |
Request body (application/json)
{ "draft": { "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 }}Response 200 (application/json)
{ "proposal_id": "string", "org_id": "string", "kind": "update", "source": "feedback", "rule_id": "string", "status": "pending", "reason": "string", "changes": { "severity": "string", "requires_review": true, "enabled": true, "description_amendment": "string" }, "evidence": { "rule_id": "string", "title": "string", "severity": "string", "confirmed": 0, "rejected": 0, "severity_wrong": 0, "unclear": 0, "total": 0, "precision": 0, "calibrating": false, "last_feedback_at": "string" }, "reviewer_quotes": [ "string" ], "draft": { "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 }, "origin": { "kind": "adr", "repository": { "provider": "github", "external_id": "string" }, "path": "string", "commit_sha": "string", "blob_sha": "string", "excerpt": "string" }, "strength": "constraint", "visibility": "unit", "created_at": "string", "decided_at": "string", "decided_by": "string"}| Field | Type | Required | Description |
|---|---|---|---|
proposal_id | string | yes | |
org_id | string | yes | |
kind | "update" | "create" | "disable" | yes | |
source | "feedback" | "knowledge" | yes | |
rule_id | string | null | yes | The rule to change. Null for a create until it is applied; then the new rule’s id. |
status | ProposalStatus | no | |
reason | string | yes | One sentence: what the evidence says |
changes | RuleProposalChanges | null | no | Feedback proposals: the edit suggested |
evidence | RuleHealth | null | no | Feedback proposals: the verdicts behind it |
reviewer_quotes | string[] | no | Verbatim reviewer comments this proposal was derived from |
draft | CustomRuleCreate | null | no | Knowledge proposals: the rule to create, or what the rule becomes |
origin | RuleOrigin | null | no | Knowledge proposals: the file it was drawn from |
strength | "constraint" | "preference" | null | no | Knowledge proposals: whether the file requires it or only recommends it |
visibility | "unit" | "pull_request" | null | no | Knowledge proposals: where a violation shows. pull_request: only across files, which a review of one unit at a time may miss. |
created_at | string | yes | |
decided_at | string | null | no | |
decided_by | string | null | no |
404— Not Found409— A feedback ordisableproposal, or one already decided
POST /v1/rule-proposals/{proposal_id}/apply
Section titled “POST /v1/rule-proposals/{proposal_id}/apply”Apply a proposed rule change
Requires admin role. Changes the rules through the same path a person’s edit takes, audited as rule.create or rule.update and attributed to the caller — plus a rule_proposal.apply event recording that a proposal was the source. A deferred proposal can be applied too.
Feedback proposals: description_amendment, when the proposal carries one, is appended to the rule’s existing Markdown description rather than replacing it. Pass changes to apply something other than what was proposed: the proposal is a recommendation, and editing the wording before keeping it is the expected workflow, not an exception.
Knowledge proposals take no body: edit the draft first with PATCH /rule-proposals/{proposal_id}. A create adds the rule, an update rewrites its title, description, severity and packs, and a disable turns it off.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
proposal_id | string | yes |
Request body (application/json, optional)
{ "severity": "string", "requires_review": true, "enabled": true, "description_amendment": "string"}| Field | Type | Required | Description |
|---|---|---|---|
severity | string | null | no | |
requires_review | boolean | null | no | |
enabled | boolean | null | no | |
description_amendment | string | null | no | Text to append to the rule’s Markdown description. Assembled from what reviewers actually wrote (services/rules/health.py) rather than paraphrased by a model — the LLM clients in libs/llm are schema-forced to UnitAnalysis and have no free-text completion, and inventing policy wording for a security rule is a human’s job. POST /rule-proposals/{id}/apply accepts an edited changes body for exactly that reason, and the rule stays editable by hand afterwards like any other. |
Response 200 (application/json)
{ "proposal_id": "string", "org_id": "string", "kind": "update", "source": "feedback", "rule_id": "string", "status": "pending", "reason": "string", "changes": { "severity": "string", "requires_review": true, "enabled": true, "description_amendment": "string" }, "evidence": { "rule_id": "string", "title": "string", "severity": "string", "confirmed": 0, "rejected": 0, "severity_wrong": 0, "unclear": 0, "total": 0, "precision": 0, "calibrating": false, "last_feedback_at": "string" }, "reviewer_quotes": [ "string" ], "draft": { "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 }, "origin": { "kind": "adr", "repository": { "provider": "github", "external_id": "string" }, "path": "string", "commit_sha": "string", "blob_sha": "string", "excerpt": "string" }, "strength": "constraint", "visibility": "unit", "created_at": "string", "decided_at": "string", "decided_by": "string"}| Field | Type | Required | Description |
|---|---|---|---|
proposal_id | string | yes | |
org_id | string | yes | |
kind | "update" | "create" | "disable" | yes | |
source | "feedback" | "knowledge" | yes | |
rule_id | string | null | yes | The rule to change. Null for a create until it is applied; then the new rule’s id. |
status | ProposalStatus | no | |
reason | string | yes | One sentence: what the evidence says |
changes | RuleProposalChanges | null | no | Feedback proposals: the edit suggested |
evidence | RuleHealth | null | no | Feedback proposals: the verdicts behind it |
reviewer_quotes | string[] | no | Verbatim reviewer comments this proposal was derived from |
draft | CustomRuleCreate | null | no | Knowledge proposals: the rule to create, or what the rule becomes |
origin | RuleOrigin | null | no | Knowledge proposals: the file it was drawn from |
strength | "constraint" | "preference" | null | no | Knowledge proposals: whether the file requires it or only recommends it |
visibility | "unit" | "pull_request" | null | no | Knowledge proposals: where a violation shows. pull_request: only across files, which a review of one unit at a time may miss. |
created_at | string | yes | |
decided_at | string | null | no | |
decided_by | string | null | no |
404— No such proposal, or the rule no longer exists409— Already applied or dismissed, or it carries no change to apply
POST /v1/rule-proposals/{proposal_id}/defer
Section titled “POST /v1/rule-proposals/{proposal_id}/defer”Set a proposed rule change aside
Requires admin role. The proposal stays open with the status deferred: nothing changes, and it can still be applied or dismissed later.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
proposal_id | string | yes |
Response 200 (application/json)
{ "proposal_id": "string", "org_id": "string", "kind": "update", "source": "feedback", "rule_id": "string", "status": "pending", "reason": "string", "changes": { "severity": "string", "requires_review": true, "enabled": true, "description_amendment": "string" }, "evidence": { "rule_id": "string", "title": "string", "severity": "string", "confirmed": 0, "rejected": 0, "severity_wrong": 0, "unclear": 0, "total": 0, "precision": 0, "calibrating": false, "last_feedback_at": "string" }, "reviewer_quotes": [ "string" ], "draft": { "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 }, "origin": { "kind": "adr", "repository": { "provider": "github", "external_id": "string" }, "path": "string", "commit_sha": "string", "blob_sha": "string", "excerpt": "string" }, "strength": "constraint", "visibility": "unit", "created_at": "string", "decided_at": "string", "decided_by": "string"}| Field | Type | Required | Description |
|---|---|---|---|
proposal_id | string | yes | |
org_id | string | yes | |
kind | "update" | "create" | "disable" | yes | |
source | "feedback" | "knowledge" | yes | |
rule_id | string | null | yes | The rule to change. Null for a create until it is applied; then the new rule’s id. |
status | ProposalStatus | no | |
reason | string | yes | One sentence: what the evidence says |
changes | RuleProposalChanges | null | no | Feedback proposals: the edit suggested |
evidence | RuleHealth | null | no | Feedback proposals: the verdicts behind it |
reviewer_quotes | string[] | no | Verbatim reviewer comments this proposal was derived from |
draft | CustomRuleCreate | null | no | Knowledge proposals: the rule to create, or what the rule becomes |
origin | RuleOrigin | null | no | Knowledge proposals: the file it was drawn from |
strength | "constraint" | "preference" | null | no | Knowledge proposals: whether the file requires it or only recommends it |
visibility | "unit" | "pull_request" | null | no | Knowledge proposals: where a violation shows. pull_request: only across files, which a review of one unit at a time may miss. |
created_at | string | yes | |
decided_at | string | null | no | |
decided_by | string | null | no |
404— Not Found409— Conflict
POST /v1/rule-proposals/{proposal_id}/dismiss
Section titled “POST /v1/rule-proposals/{proposal_id}/dismiss”Dismiss a proposed rule change
Requires admin role. The rule is untouched; the proposal stops being offered.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
proposal_id | string | yes |
Response 200 (application/json)
{ "proposal_id": "string", "org_id": "string", "kind": "update", "source": "feedback", "rule_id": "string", "status": "pending", "reason": "string", "changes": { "severity": "string", "requires_review": true, "enabled": true, "description_amendment": "string" }, "evidence": { "rule_id": "string", "title": "string", "severity": "string", "confirmed": 0, "rejected": 0, "severity_wrong": 0, "unclear": 0, "total": 0, "precision": 0, "calibrating": false, "last_feedback_at": "string" }, "reviewer_quotes": [ "string" ], "draft": { "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 }, "origin": { "kind": "adr", "repository": { "provider": "github", "external_id": "string" }, "path": "string", "commit_sha": "string", "blob_sha": "string", "excerpt": "string" }, "strength": "constraint", "visibility": "unit", "created_at": "string", "decided_at": "string", "decided_by": "string"}| Field | Type | Required | Description |
|---|---|---|---|
proposal_id | string | yes | |
org_id | string | yes | |
kind | "update" | "create" | "disable" | yes | |
source | "feedback" | "knowledge" | yes | |
rule_id | string | null | yes | The rule to change. Null for a create until it is applied; then the new rule’s id. |
status | ProposalStatus | no | |
reason | string | yes | One sentence: what the evidence says |
changes | RuleProposalChanges | null | no | Feedback proposals: the edit suggested |
evidence | RuleHealth | null | no | Feedback proposals: the verdicts behind it |
reviewer_quotes | string[] | no | Verbatim reviewer comments this proposal was derived from |
draft | CustomRuleCreate | null | no | Knowledge proposals: the rule to create, or what the rule becomes |
origin | RuleOrigin | null | no | Knowledge proposals: the file it was drawn from |
strength | "constraint" | "preference" | null | no | Knowledge proposals: whether the file requires it or only recommends it |
visibility | "unit" | "pull_request" | null | no | Knowledge proposals: where a violation shows. pull_request: only across files, which a review of one unit at a time may miss. |
created_at | string | yes | |
decided_at | string | null | no | |
decided_by | string | null | no |
404— Not Found
Detection rules
Section titled “Detection rules”The vendored Agent Threat Rules behind the injection scanner’s atr: tags.
GET /v1/detection-rules/{rule_id}
Section titled “GET /v1/detection-rules/{rule_id}”Get a detection rule
The rule behind an agent-manipulation finding: its AGENT-* rule_id, or an atr:<rule_id> tag. Title, severity, description and, for an ATR rule, cross-references (CVE, MITRE ATLAS, OWASP). Requires findings:read (member). The rules are core’s own and the vendored Agent Threat Rules subset, the same for every organization.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes |
Response 200 (application/json)
{ "rule_id": "ATR-2026-00001", "title": "string", "severity": "CRITICAL", "category": "prompt-injection", "description": "string", "references": { "key": [ "string" ] }}| Field | Type | Required | Description |
|---|---|---|---|
rule_id | string | yes | |
title | string | yes | |
severity | SeverityLevel | yes | |
category | string | yes | |
description | string | yes | |
references | object | no | Cross-references by scheme, e.g. cve, mitre_atlas, owasp_llm. |
404— No detection rule has this id
Agent-injection settings
Section titled “Agent-injection settings”An organization’s agent-injection settings: semantic scoring, which runs an LLM on the organization’s own connection and budget, and the gate an injection finding sets on a pull request.
GET /v1/orgs/{org_id}/injection-settings
Section titled “GET /v1/orgs/{org_id}/injection-settings”Get the agent-injection settings
Whether semantic scoring is on, the model it uses and the injection gate. semantic_allowed says whether the platform lets organizations turn scoring on; effective_gate is the gate that applies, the organization’s or the platform default.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "semantic_enabled": false, "connection_id": "string", "model": "string", "knowledge_sync_enabled": false, "gate": "off", "semantic_allowed": true, "effective_gate": "off"}| Field | Type | Required | Description |
|---|---|---|---|
semantic_enabled | boolean | no | Score tier 1 pattern matches with an LLM on the organization’s own connection. Takes effect only when the platform allows it (analysis.injection_scan_semantic). |
connection_id | string | null | no | The LLM connection scoring uses. Null: the connection of the review it runs in. |
model | string | null | no | The model scoring uses, on connection_id. Set both or neither. |
knowledge_sync_enabled | boolean | no | Also score the pattern matches in a file that a knowledge sync reads. A file whose matches are all scored benign is read into rule proposals; any other file stays flagged. Takes effect only when semantic_enabled does (core ADR 0039). |
gate | "off" | "review" | "fail" | null | no | What an injection finding does to a pull request’s commit status. Null: the platform default (analysis.injection_scan_gate). |
semantic_allowed | boolean | yes | Whether the platform lets organizations turn on semantic scoring. |
effective_gate | "off" | "review" | "fail" | yes | The gate that applies: the organization’s, else the platform default. |
PUT /v1/orgs/{org_id}/injection-settings
Section titled “PUT /v1/orgs/{org_id}/injection-settings”Replace the agent-injection settings
Semantic scoring runs an LLM on each pattern match in a pull request, on the organization’s own connection. It counts against the monthly LLM budget and runs only when the platform allows it. With connection_id and model null, scoring uses the review’s connection and model. With gate null, the platform default applies. knowledge_sync_enabled also scores the matches in files that a knowledge sync reads.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "semantic_enabled": false, "connection_id": "string", "model": "string", "knowledge_sync_enabled": false, "gate": "off"}| Field | Type | Required | Description |
|---|---|---|---|
semantic_enabled | boolean | no | Score tier 1 pattern matches with an LLM on the organization’s own connection. Takes effect only when the platform allows it (analysis.injection_scan_semantic). |
connection_id | string | null | no | The LLM connection scoring uses. Null: the connection of the review it runs in. |
model | string | null | no | The model scoring uses, on connection_id. Set both or neither. |
knowledge_sync_enabled | boolean | no | Also score the pattern matches in a file that a knowledge sync reads. A file whose matches are all scored benign is read into rule proposals; any other file stays flagged. Takes effect only when semantic_enabled does (core ADR 0039). |
gate | "off" | "review" | "fail" | null | no | What an injection finding does to a pull request’s commit status. Null: the platform default (analysis.injection_scan_gate). |
Response 200 (application/json)
{ "semantic_enabled": false, "connection_id": "string", "model": "string", "knowledge_sync_enabled": false, "gate": "off", "semantic_allowed": true, "effective_gate": "off"}| Field | Type | Required | Description |
|---|---|---|---|
semantic_enabled | boolean | no | Score tier 1 pattern matches with an LLM on the organization’s own connection. Takes effect only when the platform allows it (analysis.injection_scan_semantic). |
connection_id | string | null | no | The LLM connection scoring uses. Null: the connection of the review it runs in. |
model | string | null | no | The model scoring uses, on connection_id. Set both or neither. |
knowledge_sync_enabled | boolean | no | Also score the pattern matches in a file that a knowledge sync reads. A file whose matches are all scored benign is read into rule proposals; any other file stays flagged. Takes effect only when semantic_enabled does (core ADR 0039). |
gate | "off" | "review" | "fail" | null | no | What an injection finding does to a pull request’s commit status. Null: the platform default (analysis.injection_scan_gate). |
semantic_allowed | boolean | yes | Whether the platform lets organizations turn on semantic scoring. |
effective_gate | "off" | "review" | "fail" | yes | The gate that applies: the organization’s, else the platform default. |
Support assistant
Section titled “Support assistant”The support assistant answers a member’s questions from the docs and from the organization’s state, with that member’s own permissions. It reads, never writes. It runs on the organization’s LLM connection and budget, and only when the platform allows it (support.enabled) and an org admin turned it on. A conversation is visible only to the person who started it.
GET /v1/orgs/{org_id}/support-settings
Section titled “GET /v1/orgs/{org_id}/support-settings”Get the support-assistant settings
Whether the support assistant is on for the organization and the model it uses. allowed says whether the platform lets organizations turn it on; available says whether members can use it now; contact_available says whether escalations can be sent.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "enabled": false, "connection_id": "string", "model": "string", "allowed": true, "available": true, "contact_available": true}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | Offer the support assistant to the organization’s members. Takes effect only when the platform allows it (support.enabled). Needs connection_id and model. |
connection_id | string | null | no | The LLM connection the assistant uses. |
model | string | null | no | The model the assistant uses, on connection_id. Set both or neither. |
allowed | boolean | yes | Whether the platform lets organizations turn the assistant on. |
available | boolean | yes | Whether members can use the assistant now: allowed and enabled. |
contact_available | boolean | yes | Whether the platform set an address for escalations. |
PUT /v1/orgs/{org_id}/support-settings
Section titled “PUT /v1/orgs/{org_id}/support-settings”Replace the support-assistant settings
The assistant answers members’ questions from the docs and from the organization’s state, with each member’s own permissions. Each question makes up to support.max_steps LLM calls on connection_id, and they count against the monthly LLM budget. Turning it on needs connection_id and model, and takes effect only when the platform allows it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "enabled": false, "connection_id": "string", "model": "string"}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | Offer the support assistant to the organization’s members. Takes effect only when the platform allows it (support.enabled). Needs connection_id and model. |
connection_id | string | null | no | The LLM connection the assistant uses. |
model | string | null | no | The model the assistant uses, on connection_id. Set both or neither. |
Response 200 (application/json)
{ "enabled": false, "connection_id": "string", "model": "string", "allowed": true, "available": true, "contact_available": true}| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | Offer the support assistant to the organization’s members. Takes effect only when the platform allows it (support.enabled). Needs connection_id and model. |
connection_id | string | null | no | The LLM connection the assistant uses. |
model | string | null | no | The model the assistant uses, on connection_id. Set both or neither. |
allowed | boolean | yes | Whether the platform lets organizations turn the assistant on. |
available | boolean | yes | Whether members can use the assistant now: allowed and enabled. |
contact_available | boolean | yes | Whether the platform set an address for escalations. |
GET /v1/orgs/{org_id}/support/conversations
Section titled “GET /v1/orgs/{org_id}/support/conversations”List my support conversations
Newest first, without messages.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Response 200 (application/json)
{ "conversations": [ { "conversation_id": "string", "title": "string", "escalated_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z" } ]}POST /v1/orgs/{org_id}/support/conversations
Section titled “POST /v1/orgs/{org_id}/support/conversations”Ask the support assistant a first question
Starts a conversation and answers the question. The answer can take several LLM calls, which count against the organization’s monthly budget. An answer that could not settle the question carries an escalation_draft.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
org_id | string | yes |
Request body (application/json)
{ "content": "string"}| Field | Type | Required | Description |
|---|---|---|---|
content | string | yes | The user’s question. |
Response 201 (application/json)
{ "conversation_id": "string", "title": "string", "messages": [ { "role": "user", "content": "string", "sources": [ "string" ], "escalation_draft": "string", "created_at": "2026-01-01T00:00:00Z" } ], "cost_usd": 0, "escalated_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
conversation_id | string | yes | |
title | string | yes | The first question, shortened. |
messages | SupportMessage[] | yes | |
cost_usd | number | yes | What the conversation’s model calls cost the organization. |
escalated_at | string (date-time) | null | no | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes |
409— The assistant’s connection or model can no longer be used502— The model failed to answer
GET /v1/orgs/{org_id}/support/conversations/{conversation_id}
Section titled “GET /v1/orgs/{org_id}/support/conversations/{conversation_id}”Get one of my support conversations
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
conversation_id | string | yes | |
org_id | string | yes |
Response 200 (application/json)
{ "conversation_id": "string", "title": "string", "messages": [ { "role": "user", "content": "string", "sources": [ "string" ], "escalation_draft": "string", "created_at": "2026-01-01T00:00:00Z" } ], "cost_usd": 0, "escalated_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
conversation_id | string | yes | |
title | string | yes | The first question, shortened. |
messages | SupportMessage[] | yes | |
cost_usd | number | yes | What the conversation’s model calls cost the organization. |
escalated_at | string (date-time) | null | no | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes |
POST /v1/orgs/{org_id}/support/conversations/{conversation_id}/messages
Section titled “POST /v1/orgs/{org_id}/support/conversations/{conversation_id}/messages”Ask a follow-up question
Answers the question with the earlier messages as context.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
conversation_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "content": "string"}| Field | Type | Required | Description |
|---|---|---|---|
content | string | yes | The user’s question. |
Response 200 (application/json)
{ "conversation_id": "string", "title": "string", "messages": [ { "role": "user", "content": "string", "sources": [ "string" ], "escalation_draft": "string", "created_at": "2026-01-01T00:00:00Z" } ], "cost_usd": 0, "escalated_at": "2026-01-01T00:00:00Z", "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-01T00:00:00Z"}| Field | Type | Required | Description |
|---|---|---|---|
conversation_id | string | yes | |
title | string | yes | The first question, shortened. |
messages | SupportMessage[] | yes | |
cost_usd | number | yes | What the conversation’s model calls cost the organization. |
escalated_at | string (date-time) | null | no | |
created_at | string (date-time) | yes | |
updated_at | string (date-time) | yes |
409— The assistant’s connection or model can no longer be used502— The model failed to answer
POST /v1/orgs/{org_id}/support/conversations/{conversation_id}/escalate
Section titled “POST /v1/orgs/{org_id}/support/conversations/{conversation_id}/escalate”Send a conversation to support
Emails the summary and the conversation to the address the platform admin set (support.contact_email). attach_diagnostics adds the deployment’s versions and check results, and only a platform admin may set it.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
conversation_id | string | yes | |
org_id | string | yes |
Request body (application/json)
{ "summary": "string", "attach_diagnostics": false}| Field | Type | Required | Description |
|---|---|---|---|
summary | string | yes | What support staff receive. Starts as the assistant’s draft; the user edits it. |
attach_diagnostics | boolean | no | Add the deployment’s diagnostics checks and versions. Org admins only. |
Response 200 (application/json)
{ "detail": "string"}409— No support address is set