Signals
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
POST | |
GET | |
POST | |
PATCH | |
DELETE | |
POST | |
POST | |
POST | |
POST | |
POST | |
POST | |
GET | |
GET | |
POST | |
POST | |
GET | |
GET | |
GET | |
GET | |
POST |
Create signals scout chat tasks
Create and run a cloud task for one of the fixed scout chat templates (suggest a scout, fleet overview, recent signals). The prompt is server-owned; an author_scout chat can carry the user's request, which the server fences inside that prompt. The response carries the task id to navigate to.
Required API key scopes
task:writeRequest parameters
- chat_type
- suggestion_idstring
- user_promptstring
Response
Example request
POST /api /projects /:project_id /signals /scout /chat_tasksExample response
Status 201 Chat task created and run started
Status 403 Organization has not approved AI data processing
Status 429 Team is over its posthog_code usage limit
List all signals scout config
List the per-(team, skill) scout configs for this project. Each row includes its display_name (the label people read), its skill_name (the permanent identifier), its schedule (rolling run_interval_minutes, or a project-local run_cron_schedule when set), enabled, emit posture, and tags. A freshly authored scout skill appears here once its config is registered, either explicitly via create or by the coordinator's next tick. Pass tags to narrow the fleet to the scouts carrying at least one of the given labels, and search to narrow it to the scouts matching a substring of either name.
Required API key scopes
signal_scout:readQuery parameters
- searchstring
- tagsstring
Example request
GET /api /projects /:project_id /signals /scout /configsExample response
Status 200 Per-scout configs for this project, ordered by the name each scout displays under.
Create signals scout config
Register the config for a skill immediately, without waiting for the coordinator to auto-register it — and the way to make a skill without the signals-scout- prefix a scout at all. The same call can optionally set run_interval_minutes, a cron run_cron_schedule, enabled, emit, network_access, and output destinations. The skill must already exist on this project. Upsert: if a config already exists for the skill, the provided fields are applied to it. Registering puts the skill's body on the schedule as the scout's prompt, so this call needs llm_skill:write and editor access to skills on top of signal_scout:write, like creating a scout.
Required API key scopes
signal_scout:writellm_skill:writeRequest parameters
- modelstring | null
- custom_image_idstring | null
- tagsarray
- structured_output_schemaobject | null
- mcp_gateway_server_idsarray
- repositoriesarray
- write_scopesarray
- report_actionsarray
- max_report_actions_per_dayinteger
- lifecycle_lockedboolean
- allowed_mcp_toolsarray | null
- tool_preset
- precheck_querystring | null
- enabledboolean
- emitboolean
- run_interval_minutesinteger
- output_destinations
- network_access
- auto_pause_exemptboolean
- run_cron_schedulestring | null
- display_namestring
- skill_namestring
Response
Example request
POST /api /projects /:project_id /signals /scout /configsExample response
Status 200 A config already existed for this skill; the provided fields were applied to it.
Status 201 Created config.
Status 400 No such skill on this project, the name is reserved by the inbox, or the project is already at its enabled-scouts maximum.
Status 403 The caller lacks editor access to skills on this project.
Update signals scout config
Tune one scout: change its schedule (rolling run_interval_minutes, or a cron run_cron_schedule that takes precedence when set), enabled, emit (dry-run) posture, network_access (trusted-domain allowlist vs full access for the scout's sandbox), or output destinations. skill_name is fixed. Enabling records enabled_by and is activity-logged since it drives spend.
Required API key scopes
signal_scout:writePath parameters
- idstring
Request parameters
- display_namestring
- enabledboolean
- emitboolean
- run_interval_minutesinteger
- run_cron_schedulestring | null
- output_destinations
- structured_output_schemaobject | null
- network_access
- modelstring | null
- custom_image_idstring | null
- auto_pause_exemptboolean
- tagsarray
- mcp_gateway_server_idsarray
- repositoriesarray
- write_scopesarray
- report_actionsarray
- max_report_actions_per_dayinteger
- precheck_querystring | null
- precheck_disabledboolean
- suggestion_idstring
- lifecycle_lockedboolean
- allowed_mcp_toolsarray | null
- tool_preset
Response
Example request
PATCH /api /projects /:project_id /signals /scout /configs /:idExample response
Status 200 Updated config.
Status 400 Invalid fields, or enabling would exceed the project's enabled-scouts maximum.
Status 404 Config not found for this project.
Delete signals scout config
Delete one scout config by its id, removing the per-(team, skill) schedule/emit row outright. The point is cleaning up an orphaned config whose skill was archived or deleted — it lingers in list with an empty description, never runs (the coordinator skips it and the skill can't load), but can't otherwise be removed over the API. Deletion is activity-logged. Note: auto-registration only scans live signals-scout-* skills, so a config deleted for one of those is back on the coordinator's next tick. A scout under any other name does not come back on its own: its config stays deleted until you re-register it, and its skill still reads as a scout meanwhile. To retire a live scout, archive its skill (or set enabled=false to make it inert) rather than deleting the config. A scout whose scout_role is operational cannot be deleted: it is part of the self-driving system rather than the project's own fleet.
Required API key scopes
signal_scout:writePath parameters
- idstring
Example request
DELETE /api /projects /:project_id /signals /scout /configs /:idExample response
Status 204 Config deleted.
Status 400 This scout is operational and cannot be deleted.
Status 404 Config not found for this project.
Create signals scout config precheck
Run a scout's pre-check query once and return its rows, without starting a run and without saving anything. The query gets the same {since} and {now} values the next scheduled run would get, so the result says whether that run would start or skip. Pass precheck_query to try a query before you save it, or omit it to try the effective one: the saved query, or the default the scout's skill ships. A query error comes back in the error field with a 200, because a scheduled run treats it as a reason to run.
Required API key scopes
signal_scout:readquery:readPath parameters
- idstring
Request parameters
- precheck_querystring | null
Response
Example request
POST /api /projects /:project_id /signals /scout /configs /:id /precheck_testExample response
Status 200 What the pre-check returns now, and whether a scheduled run would start.
Status 400 The scout has no saved pre-check and the request gives no query.
Status 404 Config not found for this project.
Create signals scout config
Dispatch one on-demand run of this scout immediately, regardless of its schedule. Useful to test a scout right after authoring it, or to refresh its findings on demand. The run executes asynchronously on the worker and inherits every guard the scheduled path has: it is forbidden if scouts are not enabled for the project (403), and skipped if self-driving is paused at the project's pull request limit, or the project is over its daily report limit or daily run budget (429), or a run for this scout is already in progress (409). A manual run counts against the same daily run budget as scheduled runs, so repeated manual runs of the same scout can exhaust the project's daily allowance. A manual run does not change the scout's schedule or last_run_at. A disabled scout can still be run this way (to test before enabling). Pass an optional note to steer this one run without leaving a scout note that would steer every later run too. Returns immediately with the workflow id: poll the scout's runs for the result.
Required API key scopes
signal_scout:writePath parameters
- idstring
Request parameters
- notestring
Response
Example request
POST /api /projects /:project_id /signals /scout /configs /:id /runExample response
Status 202 A run was dispatched. It executes asynchronously; poll the scout's runs for the result.
Status 400 The note is longer than the limit.
Status 403 Signals scouts are not enabled for this project, or the caller may not steer a run with a note.
Status 404 Config not found for this project (or the scout is withheld).
Status 409 A run for this scout is already in progress.
Status 429 Self-driving is paused at the project's pull request limit, or the project is over its daily report limit or its daily scout run budget; try again later.
Create signals scout config
Stop the run of this scout that is in progress now. The run is cancelled the same way as a task run cancel: the agent is interrupted, the sandbox is torn down, and the run is marked cancelled, so the scout can run again. Idempotent: a run that already finished is returned unchanged. Returns 404 when the scout has no run in progress.
Required API key scopes
signal_scout:writePath parameters
- idstring
Response
Example request
POST /api /projects /:project_id /signals /scout /configs /:id /stopExample response
Status 200 The run finished before the stop reached it. It is returned unchanged.
Status 202 The stop was accepted.
Status 400 The run is not a cloud run, so it cannot be stopped here.
Status 404 Config not found for this project (or the scout is withheld), or the scout has no run in progress.
Status 503 The stop could not reach the run's workflow. It is safe to try again.
Create signals scout config
Run a prompt, model, or effort variant against live data with private memory and report capture.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Request parameters
- launch_idstring
- context_idstring
- variantstring
- skill_bodystring
- modelstring
- reasoning_effortstring
- notestring
Response
Example request
POST /api /projects /:project_id /signals /scout /configs /:id /trialExample response
Status 202
Create signals scout config trial comparison
Freeze variants and the reviewed rubric, then run scouts and judge their results in the background.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Request parameters
- comparison_idstring
- baseline_variant_idstring
- variantsarray
- notestring
- expected_skill_versioninteger
Response
Example request
POST /api /projects /:project_id /signals /scout /configs /:id /trial_comparisonExample response
Status 202
Create signals scout config trial comparison
Hide a finished trial from history or restore it without deleting results or starting any work.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Request parameters
- comparison_idstring
- archivedboolean
Response
Example request
POST /api /projects /:project_id /signals /scout /configs /:id /trial_comparison_archiveExample response
Status 200
Retrieve signals scout config trial comparison
Read recent comparisons, including those saved before any scout run started.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Query parameters
- cursorstring
- include_archivedbooleanDefault:
false - limitintegerDefault:
30
Response
Example request
GET /api /projects /:project_id /signals /scout /configs /:id /trial_comparison_historyExample response
Status 200
Retrieve signals scout config trial comparison
Read comparison progress and its saved report without starting any scout or judge calls.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Query parameters
- comparison_idstring
Response
Example request
GET /api /projects /:project_id /signals /scout /configs /:id /trial_comparison_resultExample response
Status 200
Create signals scout config trial comparison
Recover the same comparison without repeating saved scout runs or judge attempts.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Request parameters
- comparison_idstring
Response
Example request
POST /api /projects /:project_id /signals /scout /configs /:id /trial_comparison_resumeExample response
Status 202
Create signals scout config trial evaluation
Freeze rubric and evidence, then judge explicit variant groups without changing production scouts.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Request parameters
- evaluation_idstring
- baseline_variant_idstring
- variantsarray
- rubric_source
Response
Example request
POST /api /projects /:project_id /signals /scout /configs /:id /trial_evaluationExample response
Status 202
Retrieve signals scout config trial evaluation
Read saved scores, criterion evidence and baseline differences without starting model calls.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Query parameters
- evaluation_idstring
Response
Example request
GET /api /projects /:project_id /signals /scout /configs /:id /trial_evaluation_resultExample response
Status 200
Retrieve signals scout config trial
Read recent private runs for the requesting operator in the internal comparison editor.
Required API key scopes
signal_scout:writellm_skill:writePath parameters
- idstring
Query parameters
- limitintegerDefault:
30
Response
Example request
GET /api /projects /:project_id /signals /scout /configs /:id /trial_historyExample response
Status 200
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 /api /projects /:project_id /signals /scout /configs /:id /trial_resultExample 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 /api /projects /:project_id /signals /scout /configs /:id /trial_setupExample 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. With surface=onboarding, new configs stay disabled until explicitly activated.
Required API key scopes
signal_scout:writeQuery parameters
- surfacestringOne of:
"roster""desktop""wizard""onboarding"
Example request
POST /api /projects /:project_id /signals /scout /configs /sync




