Skip to content
DashboardWebsite

Endpoints: LLM Connections, Billing & Findings

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.

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

NameTypeRequiredDescription
org_idstringyes

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
}

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

NameTypeRequiredDescription
org_idstringyes

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
}
FieldTypeRequiredDescription
connection_idstringyesThis 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"yesWhich wire protocol this endpoint speaks
display_namestring | nullnoHuman label for the dashboard. Defaults to connection_id.
base_urlstring | nullnoEndpoint 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_keystring | nullnoStored encrypted. Optional only when auth_style is ‘none’.
auth_style"bearer" | "header" | "none"no
auth_headerstringno
extra_headersobjectno
tls_ca_pemstring | nullnoPEM 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" | nullnoHow 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.
enabledbooleanno

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 Request
  • 409 — connection_id already 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

NameTypeRequiredDescription
org_idstringyes
connection_idstringyes

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
}
FieldTypeRequiredDescription
display_namestring | nullno
base_urlstring | nullno
api_keystring | nullnoReplaces the stored key. Omit to keep it.
auth_style"bearer" | "header" | "none" | nullno
auth_headerstring | nullno
extra_headersobject | nullno
tls_ca_pemstring | nullnoReplaces the stored bundle. Omit to keep it.
structured_output_mode"tool_call" | "json_schema" | "json_object" | "prompt_only" | nullno
enabledboolean | nullno

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 Request
  • 404 — 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

NameTypeRequiredDescription
org_idstringyes
connection_idstringyes

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

NameTypeRequiredDescription
org_idstringyes
connection_idstringyes

Query parameters

NameTypeRequiredDescription
modelstringyes

Response 200 (application/json)

{
"reachable": true,
"latency_ms": 0,
"structured_output": false,
"usage_reported": false,
"error": "string"
}
FieldTypeRequiredDescription
reachablebooleanyes
latency_msinteger | nullno
structured_outputbooleannoWhether 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_reportedbooleannoWhether 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.
errorstring | nullno
  • 404 — Not Found

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.

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
}
FieldTypeRequiredDescription
enabledbooleanyesFalse means every route that needs a provider call answers 501; client-led analysis, where the caller’s own agent does the analysing, still works.

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

List every catalogued LLM model, including disabled ones

The full catalog, including disabled rows; filter with enabled. Superadmin only.

Query parameters

NameTypeRequiredDescription
enabledboolean | nullno

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

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
}
FieldTypeRequiredDescription
llm_backend"anthropic" | "mistral" | "openai" | "openai_compatible"yes
modelstringyesProvider-specific model name
input_price_per_1m_usdnumberyesUSD per 1,000,000 input tokens
output_price_per_1m_usdnumberyesUSD per 1,000,000 output tokens
enabledbooleanno

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

NameTypeRequiredDescription
llm_backendstringyes
modelstringyes

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

NameTypeRequiredDescription
llm_backendstringyes
modelstringyes

Response 200 (application/json)

{
"detail": "string"
}
  • 404 — Not Found

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.

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"monthly_budget_usd": 0
}
FieldTypeRequiredDescription
monthly_budget_usdnumber | nullnoMonthly spend cap in USD. null clears the cap (unlimited).

Response 200 (application/json)

{
"monthly_budget_usd": 50
}

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_usd is the cost of every usage event this month. budget_usd and remaining_usd are null when there is no cap. period is the calendar month in UTC (YYYY-MM); usage resets at its start, with no rollover.
  • billed_quantity counts the product’s billed meter for every org, whatever the plan; only billing is gated.
  • metered_cost_usd: null on free. On paid, the degressive per-unit price for the whole quantity, from the first unit (PATCH /admin/pricing). On enterprise, the overage beyond included_units_per_month at the cheapest tier: 0.0, not null, inside the commitment.
  • included_units_per_month, included_units_remaining, overage_units and committed_amount_usd describe an enterprise commitment and are null or 0 on every other plan. On an enterprise contract with no ceiling, included_units_per_month is null: unlimited, not zero.
  • trials is 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

NameTypeRequiredDescription
org_idstringyes

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
}
]
}
FieldTypeRequiredDescription
periodstringyesCalendar month this summary covers, e.g. ‘2026-07’
total_cost_usdnumberyesThis month’s recorded spend (the cost of every usage event).
budget_usdnumber | nullyes
remaining_usdnumber | nullyes
billed_meterstring | nullnoThe meter pricing applies to, or null when the product bills none.
billed_unitstring | nullnoWhat one unit of billed_meter is called.
billed_quantityintegernoUnits of billed_meter recorded this month. Metered regardless of plan_tier — only priced (metered_cost_usd) on a paying plan.
metered_cost_usdnumber | nullnoWhat 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_monthinteger | nullnoThe 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_remaininginteger | nullnoincluded_units_per_month minus billed_quantity, floored at 0. Null under the same conditions as included_units_per_month.
overage_unitsintegernoUnits 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_usdnumber | nullnoThe 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_expiredbooleannoThe contracted term’s end date has passed (OrgContract.expires_at). Advisory: an expired contract does not revoke entitlement — see OrgContract.expires_at for why.
trialsTrialUsage[] | nullnoOne entry per meter with a trial allowance. Null on a self-hosted deployment or a paying plan, where no trial applies.

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.

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

NameTypeRequiredDescription
statusstring | nullnoopen|needs_review|acknowledged|suppressed|false_positive|closed. Without it, closed findings are left out.
severitystring | nullnoe.g. CRITICAL, HIGH
rule_idstring | nullno
changesetstring | nullnoOnly findings seen under this changeset
team_idstring | nullnoOnly findings assigned to this team
repositorystring | nullnoOnly findings seen in this repository (provider/external_id)
product_idstring | nullnoOnly findings seen in this product’s repositories
resource_hashstring | nullnoOnly findings on this resource
has_ticketboolean | nullnotrue: only findings with a Jira issue. false: only findings without one.
limitintegerno
offsetintegerno

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
}

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

NameTypeRequiredDescription
daysintegerno

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
}
FieldTypeRequiredDescription
period_daysintegeryes
totalintegeryesAll findings regardless of status
by_statusobjectyes
by_severity_openobjectyesSeverity breakdown of status=open findings only
new_in_periodintegeryesFindings first seen within the window
resolved_in_periodintegeryesFindings 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

NameTypeRequiredDescription
resource_hashstringyesResource content hash
rule_idstringyesRule ID from the finding

Request body (application/json)

{
"status": "open",
"note": "string",
"reason_code": "false_positive"
}
FieldTypeRequiredDescription
statusFindingStatusyes
notestring | nullnoOptional triage note, e.g. why this was suppressed
reason_codeReasonCode | nullnoWhy, 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"
}
}
FieldTypeRequiredDescription
resource_hashstringyes
rule_idstringyes
unit_addressstringyes
severitystringyes
titlestringyes
statusFindingStatusno
first_seenstring (date-time)yes
last_seenstring (date-time)yes
occurrence_countintegerno
notestring | nullno
updated_bystring | nullno
updated_atstring (date-time) | nullno
changesetsstring[]noChangeset(s) this finding’s resource_hash has been seen under — usually one, but a content-addressed hash can be shared across changesets
assigned_team_idsstring[]noThe 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.
repositoriesstring[]noThe repositories (provider/external_id) it was seen in, added on every sighting. Its products are those repositories’ products, read when asked.
closed_inClosedIn | nullnoSet with status closed: the revision that no longer reported it
reason_codeReasonCode | nullnoThe reason given with the last triage status, if any
ticketFindingTicket | nullnoThe 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

NameTypeRequiredDescription
resource_hashstringyesResource content hash
rule_idstringyesRule ID from the finding

Request body (application/json)

{
"team_ids": [
"string"
]
}
FieldTypeRequiredDescription
team_idsstring[]yesReplaces 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"
}
}
FieldTypeRequiredDescription
resource_hashstringyes
rule_idstringyes
unit_addressstringyes
severitystringyes
titlestringyes
statusFindingStatusno
first_seenstring (date-time)yes
last_seenstring (date-time)yes
occurrence_countintegerno
notestring | nullno
updated_bystring | nullno
updated_atstring (date-time) | nullno
changesetsstring[]noChangeset(s) this finding’s resource_hash has been seen under — usually one, but a content-addressed hash can be shared across changesets
assigned_team_idsstring[]noThe 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.
repositoriesstring[]noThe repositories (provider/external_id) it was seen in, added on every sighting. Its products are those repositories’ products, read when asked.
closed_inClosedIn | nullnoSet with status closed: the revision that no longer reported it
reason_codeReasonCode | nullnoThe reason given with the last triage status, if any
ticketFindingTicket | nullnoThe 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

NameTypeRequiredDescription
resource_hashstringyesResource content hash
rule_idstringyesRule 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"
}
}
FieldTypeRequiredDescription
resource_hashstringyes
rule_idstringyes
unit_addressstringyes
severitystringyes
titlestringyes
statusFindingStatusno
first_seenstring (date-time)yes
last_seenstring (date-time)yes
occurrence_countintegerno
notestring | nullno
updated_bystring | nullno
updated_atstring (date-time) | nullno
changesetsstring[]noChangeset(s) this finding’s resource_hash has been seen under — usually one, but a content-addressed hash can be shared across changesets
assigned_team_idsstring[]noThe 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.
repositoriesstring[]noThe repositories (provider/external_id) it was seen in, added on every sighting. Its products are those repositories’ products, read when asked.
closed_inClosedIn | nullnoSet with status closed: the revision that no longer reported it
reason_codeReasonCode | nullnoThe reason given with the last triage status, if any
ticketFindingTicket | nullnoThe Jira issue tracking it, if any
  • 403 — Forbidden
  • 404 — Not Found
  • 409 — Conflict
  • 502 — 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

NameTypeRequiredDescription
resource_hashstringyesResource content hash
rule_idstringyesRule ID from the finding

Response 200 (application/json)

{
"detail": "string"
}
  • 404 — Not Found

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.

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

NameTypeRequiredDescription
rule_idstring | nullno
verdictstring | nullnoconfirmed|rejected|severity_wrong|missed|unclear
sourcestring | nullnodashboard_triage|pr_command|pr_review_comment|api
resource_hashstring | nullno
limitintegerno
offsetintegerno

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
}

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"
}
FieldTypeRequiredDescription
resource_hashstringyes
rule_idstringyes
verdictFeedbackVerdictyesWhat a human’s signal says about a finding, normalized across every source.
reason_codeReasonCode | nullno
commentstring | nullno

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"
}
FieldTypeRequiredDescription
feedback_idstringyes
org_idstringyes
resource_hashstring | nullnoNone for a comment attributed to a changeset but not to one finding
rule_idstring | nullnoNone when the signal is missed or unattributable
changesetstring | nullno
severitystring | nullnoThe 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).
verdictFeedbackVerdictyesWhat a human’s signal says about a finding, normalized across every source.
reason_codeReasonCode | nullno
commentstring | nullno
sourceFeedbackSourceyesWhere the signal came from — which decides how it is trusted and attributed.
actorstring | nullnouser_id, key_id, or GitHub login
trustedbooleanyesWhether this may influence a future prompt. Decided at write time, never recomputed.
provenanceFeedbackProvenancenoWhere 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_atstringyes
  • 404 — No finding record for this (resource_hash, rule_id) pair

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

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

NameTypeRequiredDescription
statusProposalStatus | nullno
source"feedback" | "knowledge" | nullno
kind"update" | "create" | "disable" | nullno
limitintegerno
offsetintegerno

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

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

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

NameTypeRequiredDescription
proposal_idstringyes

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"
}
FieldTypeRequiredDescription
proposal_idstringyes
org_idstringyes
kind"update" | "create" | "disable"yes
source"feedback" | "knowledge"yes
rule_idstring | nullyesThe rule to change. Null for a create until it is applied; then the new rule’s id.
statusProposalStatusno
reasonstringyesOne sentence: what the evidence says
changesRuleProposalChanges | nullnoFeedback proposals: the edit suggested
evidenceRuleHealth | nullnoFeedback proposals: the verdicts behind it
reviewer_quotesstring[]noVerbatim reviewer comments this proposal was derived from
draftCustomRuleCreate | nullnoKnowledge proposals: the rule to create, or what the rule becomes
originRuleOrigin | nullnoKnowledge proposals: the file it was drawn from
strength"constraint" | "preference" | nullnoKnowledge proposals: whether the file requires it or only recommends it
visibility"unit" | "pull_request" | nullnoKnowledge proposals: where a violation shows. pull_request: only across files, which a review of one unit at a time may miss.
created_atstringyes
decided_atstring | nullno
decided_bystring | nullno
  • 404 — Not Found
  • 409 — A feedback or disable proposal, 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

NameTypeRequiredDescription
proposal_idstringyes

Request body (application/json, optional)

{
"severity": "string",
"requires_review": true,
"enabled": true,
"description_amendment": "string"
}
FieldTypeRequiredDescription
severitystring | nullno
requires_reviewboolean | nullno
enabledboolean | nullno
description_amendmentstring | nullnoText 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"
}
FieldTypeRequiredDescription
proposal_idstringyes
org_idstringyes
kind"update" | "create" | "disable"yes
source"feedback" | "knowledge"yes
rule_idstring | nullyesThe rule to change. Null for a create until it is applied; then the new rule’s id.
statusProposalStatusno
reasonstringyesOne sentence: what the evidence says
changesRuleProposalChanges | nullnoFeedback proposals: the edit suggested
evidenceRuleHealth | nullnoFeedback proposals: the verdicts behind it
reviewer_quotesstring[]noVerbatim reviewer comments this proposal was derived from
draftCustomRuleCreate | nullnoKnowledge proposals: the rule to create, or what the rule becomes
originRuleOrigin | nullnoKnowledge proposals: the file it was drawn from
strength"constraint" | "preference" | nullnoKnowledge proposals: whether the file requires it or only recommends it
visibility"unit" | "pull_request" | nullnoKnowledge proposals: where a violation shows. pull_request: only across files, which a review of one unit at a time may miss.
created_atstringyes
decided_atstring | nullno
decided_bystring | nullno
  • 404 — No such proposal, or the rule no longer exists
  • 409 — 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

NameTypeRequiredDescription
proposal_idstringyes

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"
}
FieldTypeRequiredDescription
proposal_idstringyes
org_idstringyes
kind"update" | "create" | "disable"yes
source"feedback" | "knowledge"yes
rule_idstring | nullyesThe rule to change. Null for a create until it is applied; then the new rule’s id.
statusProposalStatusno
reasonstringyesOne sentence: what the evidence says
changesRuleProposalChanges | nullnoFeedback proposals: the edit suggested
evidenceRuleHealth | nullnoFeedback proposals: the verdicts behind it
reviewer_quotesstring[]noVerbatim reviewer comments this proposal was derived from
draftCustomRuleCreate | nullnoKnowledge proposals: the rule to create, or what the rule becomes
originRuleOrigin | nullnoKnowledge proposals: the file it was drawn from
strength"constraint" | "preference" | nullnoKnowledge proposals: whether the file requires it or only recommends it
visibility"unit" | "pull_request" | nullnoKnowledge proposals: where a violation shows. pull_request: only across files, which a review of one unit at a time may miss.
created_atstringyes
decided_atstring | nullno
decided_bystring | nullno
  • 404 — Not Found
  • 409 — 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

NameTypeRequiredDescription
proposal_idstringyes

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"
}
FieldTypeRequiredDescription
proposal_idstringyes
org_idstringyes
kind"update" | "create" | "disable"yes
source"feedback" | "knowledge"yes
rule_idstring | nullyesThe rule to change. Null for a create until it is applied; then the new rule’s id.
statusProposalStatusno
reasonstringyesOne sentence: what the evidence says
changesRuleProposalChanges | nullnoFeedback proposals: the edit suggested
evidenceRuleHealth | nullnoFeedback proposals: the verdicts behind it
reviewer_quotesstring[]noVerbatim reviewer comments this proposal was derived from
draftCustomRuleCreate | nullnoKnowledge proposals: the rule to create, or what the rule becomes
originRuleOrigin | nullnoKnowledge proposals: the file it was drawn from
strength"constraint" | "preference" | nullnoKnowledge proposals: whether the file requires it or only recommends it
visibility"unit" | "pull_request" | nullnoKnowledge proposals: where a violation shows. pull_request: only across files, which a review of one unit at a time may miss.
created_atstringyes
decided_atstring | nullno
decided_bystring | nullno
  • 404 — Not Found

The vendored Agent Threat Rules behind the injection scanner’s atr: tags.

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

NameTypeRequiredDescription
rule_idstringyes

Response 200 (application/json)

{
"rule_id": "ATR-2026-00001",
"title": "string",
"severity": "CRITICAL",
"category": "prompt-injection",
"description": "string",
"references": {
"key": [
"string"
]
}
}
FieldTypeRequiredDescription
rule_idstringyes
titlestringyes
severitySeverityLevelyes
categorystringyes
descriptionstringyes
referencesobjectnoCross-references by scheme, e.g. cve, mitre_atlas, owasp_llm.
  • 404 — No detection rule has this id

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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"semantic_enabled": false,
"connection_id": "string",
"model": "string",
"knowledge_sync_enabled": false,
"gate": "off",
"semantic_allowed": true,
"effective_gate": "off"
}
FieldTypeRequiredDescription
semantic_enabledbooleannoScore 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_idstring | nullnoThe LLM connection scoring uses. Null: the connection of the review it runs in.
modelstring | nullnoThe model scoring uses, on connection_id. Set both or neither.
knowledge_sync_enabledbooleannoAlso 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" | nullnoWhat an injection finding does to a pull request’s commit status. Null: the platform default (analysis.injection_scan_gate).
semantic_allowedbooleanyesWhether the platform lets organizations turn on semantic scoring.
effective_gate"off" | "review" | "fail"yesThe gate that applies: the organization’s, else the platform default.

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"semantic_enabled": false,
"connection_id": "string",
"model": "string",
"knowledge_sync_enabled": false,
"gate": "off"
}
FieldTypeRequiredDescription
semantic_enabledbooleannoScore 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_idstring | nullnoThe LLM connection scoring uses. Null: the connection of the review it runs in.
modelstring | nullnoThe model scoring uses, on connection_id. Set both or neither.
knowledge_sync_enabledbooleannoAlso 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" | nullnoWhat 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"
}
FieldTypeRequiredDescription
semantic_enabledbooleannoScore 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_idstring | nullnoThe LLM connection scoring uses. Null: the connection of the review it runs in.
modelstring | nullnoThe model scoring uses, on connection_id. Set both or neither.
knowledge_sync_enabledbooleannoAlso 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" | nullnoWhat an injection finding does to a pull request’s commit status. Null: the platform default (analysis.injection_scan_gate).
semantic_allowedbooleanyesWhether the platform lets organizations turn on semantic scoring.
effective_gate"off" | "review" | "fail"yesThe gate that applies: the organization’s, else the platform default.

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

NameTypeRequiredDescription
org_idstringyes

Response 200 (application/json)

{
"enabled": false,
"connection_id": "string",
"model": "string",
"allowed": true,
"available": true,
"contact_available": true
}
FieldTypeRequiredDescription
enabledbooleannoOffer the support assistant to the organization’s members. Takes effect only when the platform allows it (support.enabled). Needs connection_id and model.
connection_idstring | nullnoThe LLM connection the assistant uses.
modelstring | nullnoThe model the assistant uses, on connection_id. Set both or neither.
allowedbooleanyesWhether the platform lets organizations turn the assistant on.
availablebooleanyesWhether members can use the assistant now: allowed and enabled.
contact_availablebooleanyesWhether the platform set an address for escalations.

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"enabled": false,
"connection_id": "string",
"model": "string"
}
FieldTypeRequiredDescription
enabledbooleannoOffer the support assistant to the organization’s members. Takes effect only when the platform allows it (support.enabled). Needs connection_id and model.
connection_idstring | nullnoThe LLM connection the assistant uses.
modelstring | nullnoThe 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
}
FieldTypeRequiredDescription
enabledbooleannoOffer the support assistant to the organization’s members. Takes effect only when the platform allows it (support.enabled). Needs connection_id and model.
connection_idstring | nullnoThe LLM connection the assistant uses.
modelstring | nullnoThe model the assistant uses, on connection_id. Set both or neither.
allowedbooleanyesWhether the platform lets organizations turn the assistant on.
availablebooleanyesWhether members can use the assistant now: allowed and enabled.
contact_availablebooleanyesWhether 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

NameTypeRequiredDescription
org_idstringyes

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

NameTypeRequiredDescription
org_idstringyes

Request body (application/json)

{
"content": "string"
}
FieldTypeRequiredDescription
contentstringyesThe 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"
}
FieldTypeRequiredDescription
conversation_idstringyes
titlestringyesThe first question, shortened.
messagesSupportMessage[]yes
cost_usdnumberyesWhat the conversation’s model calls cost the organization.
escalated_atstring (date-time) | nullno
created_atstring (date-time)yes
updated_atstring (date-time)yes
  • 409 — The assistant’s connection or model can no longer be used
  • 502 — 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

NameTypeRequiredDescription
conversation_idstringyes
org_idstringyes

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"
}
FieldTypeRequiredDescription
conversation_idstringyes
titlestringyesThe first question, shortened.
messagesSupportMessage[]yes
cost_usdnumberyesWhat the conversation’s model calls cost the organization.
escalated_atstring (date-time) | nullno
created_atstring (date-time)yes
updated_atstring (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

NameTypeRequiredDescription
conversation_idstringyes
org_idstringyes

Request body (application/json)

{
"content": "string"
}
FieldTypeRequiredDescription
contentstringyesThe 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"
}
FieldTypeRequiredDescription
conversation_idstringyes
titlestringyesThe first question, shortened.
messagesSupportMessage[]yes
cost_usdnumberyesWhat the conversation’s model calls cost the organization.
escalated_atstring (date-time) | nullno
created_atstring (date-time)yes
updated_atstring (date-time)yes
  • 409 — The assistant’s connection or model can no longer be used
  • 502 — 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

NameTypeRequiredDescription
conversation_idstringyes
org_idstringyes

Request body (application/json)

{
"summary": "string",
"attach_diagnostics": false
}
FieldTypeRequiredDescription
summarystringyesWhat support staff receive. Starts as the assistant’s draft; the user edits it.
attach_diagnosticsbooleannoAdd the deployment’s diagnostics checks and versions. Org admins only.

Response 200 (application/json)

{
"detail": "string"
}
  • 409 — No support address is set