Signals
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
GET | |
GET | |
POST | |
GET | |
GET | |
GET | |
GET | |
POST | |
DELETE | |
GET | |
GET | |
POST | |
GET | |
GET | |
POST | |
POST | |
GET | |
GET | |
POST |
Retrieve signals scout config trial
Read a trial's existing run status and its privately captured reports and memory changes.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Query parameters
- launch_idstring
Response
Example request
GET Example response
Status 200
Retrieve signals scout config trial
Read comparison readiness and source settings for the internal comparison editor.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Query parameters
- context_idstring
Response
Example request
GET Example response
Status 200
Create signals scout config
Materialize the scout fleet for this project on demand (idempotent): seed the canonical signals-scout-* skills, create a default-schedule config for any scout lacking one, retire the skills whose canonical scout no longer ships, and return all scout configs. Normally the Temporal coordinator does this on its next tick; this action exists so the scout UIs and setup flows (e.g. the wizard's self-driving program) can hand the user a tunable fleet immediately.
Required API key scopes
signal_scout:writeQuery parameters
- surfacestringOne of:
"roster""desktop""wizard"
Example request
POST Example response
Status 200 The team's full scout fleet after the sync, ordered by skill name.
Retrieve signals scout config tool
List every MCP tool a scout could be configured with. Each entry carries the tool's name, label, one-line summary, category, and required scopes, plus holdable: whether a scout run can hold every scope the tool needs, and missing_scopes: what it would have to be granted on top of the baseline preset. The response also returns the scout scope presets and the write scopes a person can grant to one scout, so a caller can show why a tool is out of reach. Tools a successor has replaced are left out. A tool can carry a feature_flag, which resolves per project: evaluate it for the project you are configuring before you offer the tool. Read-only, and the same for every project.
Required API key scopes
signal_scout:readResponse
Example request
GET Example response
Status 200 Every catalogued MCP tool, with the scout scope postures to read it against.
List all signals scout members
Return the people who can review work on this project — one row per member with access to it, each with their user_uuid, email, first_name/last_name, resolved GitHub login (null when they have no linked GitHub identity), and the teams they're on. The cold-start reviewer-routing path: when a finding's owner can't be read off a fetched entity's created_by and there's no cached reviewer:<area> memory or inbox precedent, list members, match the owner by email/name, then put their resolved github_login in suggested_reviewers on emit-report / edit-report. Pass team to resolve a team slug to the people on it, maintainers first. Pass search to narrow a large roster; the result is capped at 200. Strictly team-scoped.
Required API key scopes
signal_scout_internal:readQuery parameters
- searchstring
- teamstring
Example request
GET Example response
Status 200 The project's members, each with their routing identity.
Retrieve signals scout metadata
Return the project's scout metadata: whether it is enrolled, the current announcement banner (e.g. an alpha run-limit notice, or null when unset), and the enforced run limits with current usage. Limits reflect what the coordinator actually applies at dispatch, so a user can see the real throttle rather than what they assume they set. All values come from the signals-scout flag payload, so the banner and caps can change with no deploy.
Required API key scopes
signal_scout:readResponse
Example request
GET Example response
Status 200 This project's scout enrollment, announcement banner, and enforced run limits.
List all signals scout notes
Return the steering notes left for this project's scouts, newest first. Pass skill_name to get the notes addressed to one scout (or one pipeline audience, e.g. pipeline:report-research) plus the general (blank-target) fleet-wide notes — the shape a scout run reads at cold start. Omit skill_name to browse every note. Expired notes are excluded unless include_expired=true. date_from / date_to are a half-open window on created_at (>= date_from, < date_to); pass date_to (the created_at of the oldest note seen) to walk past the cap. Pass text to keep only the notes whose content contains it, case-insensitively. Results capped at 500.
Required API key scopes
signal_scout:readQuery parameters
- content_max_charsinteger
- date_fromstring
- date_tostring
- include_expiredbooleanDefault:
false - include_generalbooleanDefault:
true - limitinteger
- skill_namestring
- textstring
Example request
GET Example response
Status 200 Matching notes newest-first.
Create signals scout notes
Leave a steering note the scout fleet reads on its next runs. Address it to one scout via skill_name (a configured scout), to one stage of the report pipeline via a reserved audience (pipeline:report-research), or omit it for a general note every scout sees. Each call creates a new note (no upsert); delete retires one. Attributed to the authenticated user.
Required API key scopes
signal_scout:writellm_skill:writeRequest parameters
- contentstring
- skill_namestring
- expires_atstring | null
Response
Example request
POST Example response
Status 201 The note as created.
Status 400 Invalid note (empty content, oversized, bad skill_name target).
Delete signals scout notes
Delete one note by its id, retiring it from every scout's view. Use this when a note has been acted on or no longer applies; time-boxed notes can instead carry an expires_at and retire themselves.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Example request
DELETE Example response
Status 204 Note deleted.
Status 404 Note not found for this project.
Retrieve signals scout project profile
Return the team's deterministic project profile. The response opens with a compact summary envelope carrying the emit gate and the inbox report counts, then the full payload. The inventory runs to tens of kilobytes, so a client that truncates a long tool result still keeps the gate. Pass summary_only=true to omit payload entirely. For the internal scout token the response reflects the newest non-expired cached row or a freshly-built one (lazy compute on cache miss); force_refresh=true skips the cache and rebuilds from authoritative sources. Public read callers (session auth or a signal_scout:read PAK) get the newest cached profile, or 404 if none has been built yet — they never trigger a rebuild. Read this at the start of a run to orient on the team's product mix, integrations, warehouse sources, signal coverage, and existing inbox surface.
Required API key scopes
signal_scout:readQuery parameters
- force_refreshbooleanDefault:
false - run_idstring | null
- summary_onlybooleanDefault:
false
Response
Example request
GET Example response
Status 200 The team's current project profile (cached, or freshly built for the internal scout token).
Status 404 No profile has been built for this team yet, and the caller is not the internal scout token (which builds on cache miss). Public read callers never trigger a build.
Retrieve signals scout rubrics
Required API key scopes
signal_scout:readPath parameters
- idstring
Response
Example request
GET Example response
Status 200
Create signals scout rubrics
Required API key scopes
signal_scout:writePath parameters
- idstring
Request parameters
- contextstringDefault:
Response
Example request
POST Example response
Status 202
List all signals scout runs
Return the most recent SignalScoutRun summaries for this project, newest first. Used by the headless scout to dedupe against work other runs already covered. ILIKE matches on summary. date_from / date_to are a half-open window on created_at (>= date_from, < date_to); pass date_to on subsequent calls to walk past the 100-row cap. Pass emitted=true to see only runs that surfaced at least one finding. Pass skill_name (optionally with skill_version) to scope to a single scout. Results capped at 100.
Required API key scopes
signal_scout:readQuery parameters
- date_fromstring
- date_tostring
- emittedboolean | null
- limitinteger
- skill_namestring
- skill_versioninteger
- textstring
Example request
GET Example response
Status 200 Recent run summaries newest-first.
Retrieve signals scout runs
Return the full SignalScoutRun row. Status, timing, and error flow from the linked tasks.TaskRun. Strictly team-scoped — a UUID belonging to another team returns 404.
Required API key scopes
signal_scout:readPath parameters
- run_idstring
Response
Example request
GET Example response
Status 200 Full run detail.
Status 404 Run not found or not visible to this project.
Create signals scout record check
Close the follow-up check this run was dispatched to answer. The run note carries the check id and what to establish; this call is the only thing that records the answer, so a run that investigates and says nothing leaves the check unanswered. The verdict lands on the report as a check_result entry people read in the inbox. failed retires the check, passed re-arms a recurring one, and errored retries it. inconclusive with the awaiting_data reason looks again later, and any other reason ends the check. Send the outcome you actually reached rather than the one that closes the loop. A run may close the check it was dispatched for, or a check on its own scout that is due or waiting on a run.
Required API key scopes
signal_scout_internal:writePath parameters
- run_idstring
Request parameters
- check_idstring
- outcome
- reason
- explanationstring
- observed_valuenumber | null
Response
Example request
POST Example response
Status 200 Verdict recorded on the report, and the check advanced or retired.
Status 400 The check does not exist for this project, already finished, waits for its report to resolve, is measured by the coordinator rather than a run, runs on another scout, or is neither waiting on a run nor due.
Status 404 Run not found for this project.
Create signals scout edit
Rewrite a report's title/summary, append a note or fresh evidence, set its suggested reviewers, and/or point it at another repository. Can target ANY of the project's inbox reports, not just scout-authored ones — so the edit is attributed to this scout. Reviewers and repository are how you rescue a report that surfaced routed to no one or against the wrong codebase: each replaces what the report holds and re-runs autostart, so a report that was missing a qualifying reviewer or a repository can open a draft PR. The response carries the repository the report holds after the edit, and the call fails when a repository it named did not land. Set actionability and/or priority (each with its explanation) when new evidence changed your judgment: each replaces the report's decision and re-runs autostart, without changing the report's inbox status. Title/summary edits are best-effort: the pipeline may later re-research them. Set supersedes_implementation alongside a rewrite when the fix changed. Verified automated predecessor PRs close only after the replacement completes with verified open PRs.
Required API key scopes
signal_scout_report:writePath parameters
- run_idstring
Request parameters
- report_idstring
- titlestring | null
- summarystring | null
- append_notestring | null
- corroboration_onlyboolean
- append_evidencearray | null
- suggested_reviewersarray
- repositorystring | null
- chartsarray | null
- metricsarray | null
- suggested_promptsarray | null
- linksarray
- supersedes_implementationboolean
- actionability
- actionability_explanationstring | null
- already_addressedboolean | null
- priority
- priority_explanationstring | null
Response
Example request
POST Example response
Status 200 Report edited.
Status 400 Nothing to edit, empty note, or report not found for this project.
Status 404 Run not found for this project.
Retrieve signals scout runs
Return the findings a SignalScoutRun emitted to the inbox, newest first — one row per emit with its description (the finding text as surfaced), severity, and the deterministic source_id that joins back to the underlying signal. Lets a team and its agents see what a run surfaced without parsing emitted_finding_ids or scanning the signal store. Strictly team-scoped — a run UUID belonging to another team returns 404.
Required API key scopes
signal_scout:readPath parameters
- run_idstring
Example request
GET Example response
Status 200 Findings this run emitted to the inbox, newest first.
Status 404 Run not found or not visible to this project.
Retrieve signals scout runs emission
Best-effort reverse of the report -> signals link. For each finding the run emitted, resolve the inbox SignalReport (if any) its underlying signal grouped into by walking the deterministic source_id back through the signal store. report is null when the finding hasn't grouped into a report yet, was de-duplicated away, or its signal was deleted. Lets the scout UI surface which inbox report a finding contributed to — the reverse of the report's evidence list. Strictly team-scoped — a run UUID belonging to another team returns 404.
Required API key scopes
signal_scout:readtask:readPath parameters
- run_idstring
Example request
GET Example response
Status 200 Per-finding inbox report links for this run, newest finding first.
Status 404 Run not found or not visible to this project.
Create signals scout emit
The second emit channel: author a complete SignalReport directly instead of emitting a weak signal. The report passes the safety judge, then surfaces at the status the scout's actionability call implies (or is suppressed). Backing evidence is written as bound signals so the report behaves like a pipeline report. Safe to retry: resending an emission returns the report the first call authored (idempotent_replay true) rather than a second one, keyed on idempotency_key or, without one, on the report's content. Use reports to find a report from an earlier run and edit-report to update it instead of authoring a near-duplicate.
Required API key scopes
signal_scout_report:writePath parameters
- run_idstring
Request parameters
- titlestring
- summarystring
- evidencearray
- actionability_explanationstring
- actionability
- already_addressedbooleanDefault:
false - repositorystring | null
- priority
- priority_explanationstring | null
- suggested_reviewersarray
- chartsarray
- metricsarray
- suggested_promptsarray
- linksarray
- idempotency_keystring | null
Response
Example request
POST