Signals
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
POST | |
GET | |
POST | |
POST | |
GET | |
GET | |
GET | |
POST | |
POST | |
GET | |
GET | |
GET | |
POST | |
GET | |
GET | |
POST | |
GET | |
PATCH | |
POST | |
POST |
Create signals report checks replace
Atomically replace an open agent or metric check with a metric check. The old check stays live if the new one is invalid.
Required API key scopes
inbox:writequery:readPath parameters
- idstring
- report_idstring
Request parameters
- titlestring
- rationalestring
- config
- soak_minutesinteger
- run_interval_minutesinteger
- runs_remaininginteger
Response
Example request
POST /api /projects /:project_id /signals /reports /:report_id /checks /:id /replaceExample response
Status 200
Retrieve signals reports available reviewers
Required API key scopes
inbox:readQuery parameters
- querystring
Example request
GET /api /projects /:project_id /signals /reports /available_reviewersExample response
Status 200 Up to 100 candidate reviewers keyed by user UUID.
Create signals reports bulk state
Transition many reports to a new state in one call.
Each id is processed independently: a report whose transition isn't allowed from its
current status is reported as skipped (a 409 on the single-report endpoint) and the
rest still go through. Returns one result per requested id (in request order, after
de-duplication) plus per-outcome counts. The whole call is 200 even on partial failure —
inspect results / the counts to see what happened.
Required API key scopes
inbox:writeRequest parameters
- state
- dismissal_reason
- dismissal_notestring
- corrected_repositorystring
- snooze_forinteger
- idsarray
Response
Example request
POST /api /projects /:project_id /signals /reports /bulk-stateExample response
Status 200
Create signals reports bulk
Claim many reports for the current user, internal task, or external agent in one call. Each id is claimed independently, and the call is 200 even when some claims are refused: inspect results and the counts. Use the single-report claim endpoint to release a claim or to add pull requests.
Required API key scopes
inbox:writeRequest parameters
- idsarray
- takeover_agent_claimsbooleanDefault:
false
Response
Example request
POST /api /projects /:project_id /signals /reports /bulk_claimExample response
Status 200
Retrieve signals reports for me
Your open inbox reports, ranked for you by one language model call over your activity summary, the reports that need you and the ranking model's predictions. Each entry has a reason and a compact report. The request never waits on the model. By default it returns the last stored list quickly, and checked_at says how current it is. Pass max_age_minutes to check an older list against every candidate report, which can take some seconds. refresh, focus and your first request start a background build and set building: true. With no stored list, the request returns your reports in inbox order with fallback_reason: building. Pass wait_seconds to wait a short time for the new list. Only the user the list is about can read it.
Required API key scopes
inbox:readQuery parameters
- focusstring
- limitinteger
- max_age_minutesinteger
- refreshbooleanDefault:
false - wait_secondsintegerDefault:
0
Response
Example request
GET /api /projects /:project_id /signals /reports /for_meExample response
Status 200
Status 404 Personal ranking is not available to the caller.
Retrieve signals reports pr ci
Resolve the coarse CI rollup of the pull requests several reports opened, so a list of reports can show which pull requests are red without opening each report. One GitHub call covers the whole batch, and the answers are cached briefly and shared across callers. A report is left out when it has no open implementation pull request, and also when GitHub could not answer for it (no integration reaches the repository, a rate limit, an upstream failure), so a caller shows no CI state for it rather than an error. For the individual checks behind the rollup, use pr_checks.
Required API key scopes
inbox:readQuery parameters
- report_idsstring
Response
Example request
GET /api /projects /:project_id /signals /reports /pr_ci_statusesExample response
Status 200 The CI rollup of each requested report's implementation pull request.
Status 400 `report_ids` is missing, not a list of UUIDs, or over the cap.
List all signals reports ranking outcomes
What each public outcome of the served ranking model predicts, with its horizon, cohort, base rate and readability from the model that scored this project's reports. Users who cannot see the ranking model get status not_available and no outcomes.
Required API key scopes
inbox:readResponse
Example request
GET /api /projects /:project_id /signals /reports /ranking_outcomesExample response
Status 200
Create signals reports read state
Required API key scopes
inbox:readRequest parameters
- report_idsarray
- readboolean
Response
Example request
POST /api /projects /:project_id /signals /reports /read_stateExample response
Status 200
Create signals reports refresh metrics
Re-run the stored metric queries of the given reports through the query cache and save the newest values as their snapshots. Call it when a person opens the inbox list or a report, with the ids on screen. Report titles and summaries are point-in-time text and never change here; only value, value_at, and series do, and legacy comparisons are cleared. A snapshot measured in the last 15 minutes is served as is. Each call runs at most 40 source series inside a 20-second budget, row metrics first; the rest keep their previous snapshot until the next open. Returns snapshot-only metrics for every requested report the caller can read whose status is ready or pending_input, or monitoring when Monitoring is enabled. A report in any other status is left out of the response, and its saved snapshots stay as they are.
Required API key scopes
inbox:readRequest parameters
- report_idsarray
Response
Example request
POST /api /projects /:project_id /signals /reports /refresh_metricsExample response
Status 200
Retrieve signals reports refund summary
Aggregate credited-path refunds across the whole organization for the current billing period — counts only, no per-team detail. The billing usage widget needs this because billing usage is org-wide while reports (and their refunds) are team-scoped: subtract the refunded credits from billing usage to show the net PR count. Excluded-path refunds never reach billing usage, so no adjustment is needed for them. Also carries the org's live billable credits for the period (billing's recorded usage lags by up to a day), so the widget can count just-created PRs and react to same-day refunds.
Required API key scopes
inbox:readResponse
Example request
GET /api /projects /:project_id /signals /reports /refund-summaryExample response
Status 200 Org-wide credited-refund totals for the current billing period.
Status 404 Refunds are not enabled for this organization.
Retrieve signals reports
Rank the project's inbox reports by how well they match a query, best match first. A hybrid search merges keyword matches on the title and summary with semantic matches on the report's meaning. Reports older than 3 months can match on keywords only. Returns at most 25 results, with no total count and no pages: rephrase the query for different results.
Required API key scopes
inbox:readQuery parameters
- created_afterstring
- include_unlistedbooleanDefault:
false - limitintegerDefault:
10 - querystring
- search_modestringDefault:
hybridOne of:"hybrid""semantic""keyword" - statusstring
Response
Example request
GET /api /projects /:project_id /signals /reports /searchExample response
Status 200
Status 404 Report search is not available for this project.
Status 503 A `semantic` search could not run. A `hybrid` search never returns this.
Retrieve signals reports section counts
Count the ready reports with and without an implementation pull request, in one query. Accepts the list's filters, so each count matches a count_only list request with status=ready and the matching has_implementation_pr. Rejects status, has_implementation_pr, include_all_statuses and view, because the counts set those.
Required API key scopes
inbox:readQuery parameters
- actionabilitystring
- already_addressedboolean
- assigneestringOne of:
"me""mine" - channel_idstring
- connectedstring
- created_afterstring
- created_beforestring
- excludearray
- include_unlistedbooleanDefault:
false - needs_youboolean
- prioritystring
- ranking_min_liftstring
- ranking_min_probabilitystring
- scopestring
- scoutstring
- scout_prefixstring
- searchstring
- source_idstring
- source_productstring
- suggested_reviewersstring
- tagsarray
- task_idstring
- teammate_uuidstring
- unclaimedboolean
- unreadboolean
- use_priority_preferenceboolean
Response
Example request
GET /api /projects /:project_id /signals /reports /section_countsExample response
Status 200
Create signals reports source metadata
Read which source products contributed signals to each given report, and which scout authored it. These values come from ClickHouse, so the inbox list skips them (include_source_metadata=false) and calls this after the rows render. Returns one entry per requested id. An id with no signals in this project gets empty values.
Required API key scopes
inbox:readRequest parameters
- report_idsarray
Response
Example request
POST /api /projects /:project_id /signals /reports /source_metadataExample response
Status 200
Retrieve signals reports tag options
Required API key scopes
inbox:readResponse
Example request
GET /api /projects /:project_id /signals /reports /tag_optionsExample response
Status 200
List all signals reviewer exclusions
List the standing instructions that keep you off automatic reviewer selection, active and revoked.
Required API key scopes
inbox:readExample request
GET /api /projects /:project_id /signals /reviewer_exclusionsExample response
Status 200
Create signals reviewer exclusions
Required API key scopes
inbox:writeRequest parameters
- repositorystring
- path_prefixstring
- instructionstring
- report_idstring
Response
Example request
POST /api /projects /:project_id /signals /reviewer_exclusionsExample response
Status 200 An active instruction already covers this area, so nothing new is saved.
Status 201
Status 207 The report removal succeeded but the instruction is not saved. Send the request again.
Status 400
Status 404
Retrieve signals reviewer exclusions
Required API key scopes
inbox:readPath parameters
- idstring
Response
Example request
GET /api /projects /:project_id /signals /reviewer_exclusions /:idExample response
Status 200
Update signals reviewer exclusions
Required API key scopes
inbox:writePath parameters
- idstring
Request parameters
- repositorystring
- path_prefixstring
- instructionstring
Response
Example request
PATCH /api /projects /:project_id /signals /reviewer_exclusions /:idExample response
Status 200
Status 400
Create signals reviewer exclusions revoke
Make you eligible for automatic reviewer selection in this area again. Revoking does not add you to any report, and it does not change old reports.
Required API key scopes
inbox:writePath parameters
- idstring
Response
Example request
POST /api /projects /:project_id /signals /reviewer_exclusions /:id /revokeExample response
Status 200
Create signals scout
Create a scout skill and its runnable config atomically. Give it a display_name — the label people read, kept exactly as written — and the scout's permanent skill name is generated from it, with a numeric suffix when that name is taken, so two scouts may share a label without sharing an identity. Pass name instead to pick that identifier yourself; any valid skill name works, since the config row is what makes a skill a scout. The skill always receives the report-channel tools. The optional config controls schedule, enablement, dry-run posture, network access, and typed destinations such as Slack. Repeating the same definition is safe and applies any supplied config fields; reusing an explicit name for a different definition returns 409.
Required API key scopes
llm_skill:writesignal_scout:writeRequest parameters
- display_namestring
- namestring
- descriptionstring
- bodystring
- filesarray
- config
- suggestion_idstring
Response
Example request
POST /api /projects /:project_id /signals /scout




