Signals
For instructions on how to authenticate to use this endpoint, see API overview.
Endpoints
PATCH | |
DELETE | |
GET | |
POST | |
POST | |
POST | |
GET | |
POST | |
POST | |
DELETE | |
GET | |
GET | |
POST | |
PATCH | |
DELETE | |
POST | |
DELETE |
Update signals reports
Edit the human-facing title and/or summary (description) of a signal report, addressed by id. Both fields are optional — supply only the ones you want to change; at least one is required. Every other report field (status, weights, judgments) is managed by the signals pipeline and cannot be set here. Returns the full updated report.
Required API key scopes
inbox:writetask:writePath parameters
- idstring
Request parameters
- titlestring
- summarystring
Response
Example request
PATCH /api /projects /:project_id /signals /reports /:idExample response
Status 200 Report updated.
Status 400 Neither title nor summary supplied, or a value failed validation.
Status 404 Report not found for this project.
Delete signals reports
Soft-delete a report and its signals via the deletion workflow.
Required API key scopes
inbox:writePath parameters
- idstring
Response
Example request
DELETE /api /projects /:project_id /signals /reports /:idExample response
Status 200 A deletion is already running.
Status 202 Deletion started.
List all signals reports actions
List the actions on this report that start an agent run, read from the report's current state. get_it_merged is available only while the report has an open, approved pull request. make_it_green is available only while CI fails on the report's open pull request, or while it conflicts with its base branch. resolve_conflicts is available only while the report's open pull request conflicts with its base branch. implement is available only while the report is ready and actionable, or waiting on input, has no pull request, is not a plan, has no implementation run in progress, and nobody else holds its claim. suggested_prompt has one entry per prompt the report suggests. Start one with the run endpoint.
Required API key scopes
inbox:readPath parameters
- idstring
Response
Example request
GET /api /projects /:project_id /signals /reports /:id /actionsExample response
Status 200
Create signals reports actions run
Create a task linked to the report and start its first run in the background, with the instructions the inbox uses for the same action. ask sends your own message with the framing of the inbox's Ask AI. implement starts the run the inbox's Implement button starts: it claims the report, and the pull request it opens is attached to the report. The run shows in the report's runs and counts toward the report's task limit. Nobody can answer questions in a background run, so the agent writes a note to the report's work log when it needs a decision. A task sandbox cannot start an action, except a scout run that a person granted the action in the scout's settings.
Required API key scopes
inbox:writetask:writePath parameters
- idstring
Request parameters
- action
- suggested_prompt_indexinteger
- messagestring
- repositorystring
Response
Example request
POST /api /projects /:project_id /signals /reports /:id /actions /runExample response
Status 201 Task created
Status 400 The action is not available on this report now (code `report_action_unavailable`), the `repository` is not connected to this project (code `report_action_repository_unavailable`), or no repository could be resolved for `implement` (code `report_implementation_repository_unresolved`)
Status 402 The organization is on a Self-driving free trial (code `self_driving_free_trial`)
Status 403 AI data processing is not approved, the request came from a task sandbox, or `implement` needs code access the caller does not have. A sandbox that is not a scout run gets `report_action_sandbox_refused`. A scout run that was not granted the action gets `report_action_not_granted`, and `get_it_merged` always does.
Status 404 The report has no suggested prompt at that index
Status 409 A run is already working on this report's pull request, or for `implement`, an implementation run is still in progress (code `report_action_run_active`). The body carries its `task_id` and `run_id` once that run has started.
Status 429 The report reached its task limit (code `signal_report_task_cap`), the per-user creation limit fired (code `throttled`), a scout reached its daily report action cap (code `report_action_scout_daily_cap`), or the organization reached its usage limit or is deactivated
Create signals reports
Start or update work for the current user, internal task, or external agent. Supply claim_id to resume, pull_requests to add PRs, takeover=true to explicitly take ownership, or release=true to end ownership while preserving work history and PR links. Adding PRs needs task:write as well as inbox:write.
Required API key scopes
inbox:writePath parameters
- idstring
Request parameters
- claim_idstring
- pull_requestsarray
- takeoverbooleanDefault:
false - takeover_claim_idstring
- pr_urlstring
- releasebooleanDefault:
false
Response
Example request
POST /api /projects /:project_id /signals /reports /:id /claimExample response
Status 200 Current report and assignment.
Status 400 The pull request URL or request shape is invalid.
Status 409 The report cannot be claimed or released in its current state, or another person holds the claim and the takeover has no takeover_claim_id.
Create signals reports feedback
Record the thumbs rating at the end of a report, with an optional note. For browser-session requests the rating is persisted as a per-person report action, which counts as consumption evidence for the scout that authored the report (scouts whose output nobody consumes are eventually paused); requests authenticated any other way record no action. When a note is present and the report was authored by a scout, the note is also forwarded to that scout as a steering note it reads on its next run; for any other report there is nothing to steer. The report's state is never changed.
Required API key scopes
inbox:readPath parameters
- idstring
Request parameters
- sentiment
- notestringDefault:
Response
Example request
POST /api /projects /:project_id /signals /reports /:id /feedbackExample response
Status 200
Retrieve signals reports feedback state
Required API key scopes
inbox:readPath parameters
- idstring
Response
Example request
GET /api /projects /:project_id /signals /reports /:id /feedback_stateExample response
Status 200
Create signals reports merge
Fold one or more duplicate reports into this report, which survives. The sources' signals, work-log artefacts, pull requests, task runs and checks move onto the survivor, the survivor's signal counters take on theirs, and each source is archived with a 'duplicate of' link back to the survivor. A source's open pull request stays open, because the survivor holds it after the move. Pick the survivor deliberately: prefer the older report, and prefer the one with an open implementation PR or an active claim. Any active claim on a source is released, so re-claim the survivor if you were working on one. Titles and summaries are not combined, so edit it afterwards if it needs a rewrite. A merged report keeps its URL but cannot be restored, because its signals now belong to the survivor.
Required API key scopes
inbox:writePath parameters
- idstring
Request parameters
- source_report_idsarray
- reasonstring
Response
Example request
POST /api /projects /:project_id /signals /reports /:id /mergeExample response
Status 200 The surviving report after the merge, plus one result per merged source.
Status 404 The surviving report was not found in this project.
Status 409 Both ends of a merge must be a live report of this project. Returned when the survivor is resolved, or when a source is the survivor itself, is resolved or archived, is still being researched, carries more signals than one merge can move, or belongs to another project. Nothing is applied.
Create signals reports plan steps
Link an existing report to this report as a plan step, with part_of. A report becomes a plan when it gets its first step. The step goes last in plan order. When the step is already resolved or archived and every other step is too, the plan closes the same way a plan closes when its last step does.
Required API key scopes
inbox:writePath parameters
- idstring
Request parameters
- report_idstring
- depends_onarray
- reasonstring
Response
Example request
POST /api /projects /:project_id /signals /reports /:id /plan_stepsExample response
Status 200 The plan report, with the new step in `plan.steps`.
Status 400 The edit breaks a link rule: the step is the plan itself or a report not found in this project, a `depends_on` id is not another step of this plan, or a link would close a cycle. `error` names the rule.
Status 404 The plan report was not found in this project.
Status 409 The report is already a step of this plan or of another plan.
Delete signals reports plan steps
Remove the step's part_of link to this plan, and every depends_on link between the step and the plan's other steps. The step report keeps its status, pull requests and claim. A note on the step and on the plan records the removal. When every step left is resolved or archived, the plan closes.
Required API key scopes
inbox:writePath parameters
- idstring
- step_idstring
Query parameters
- reasonstring
Response
Example request
DELETE /api /projects /:project_id /signals /reports /:id /plan_steps /:step_idExample response
Status 200 The plan report, without the step in `plan.steps`.
Status 400 The edit breaks a link rule: the step is the plan itself or a report not found in this project, a `depends_on` id is not another step of this plan, or a link would close a cycle. `error` names the rule.
Status 404 The plan report was not found in this project.
Status 409 The report is not a step of this plan.
Retrieve signals report pr
Fetch the CI status (GitHub Actions check runs and legacy commit statuses) of the pull request attached to the report, via the team's GitHub integration.
Required API key scopes
inbox:readPath parameters
- idstring
Query parameters
- pull_request_idstring
Response
Example request
GET /api /projects /:project_id /signals /reports /:id /pr_checksExample response
Status 200 The CI checks on the report's implementation pull request.
Status 403 GitHub is connected without permission to read pull request checks (code `github_checks_permission_missing`), or the GitHub App installation is suspended or uninstalled (code `github_installation_unavailable`). Both carry a `remediation_url`.
Status 404 Report has no implementation PR, or no GitHub integration can access it (code `github_repository_inaccessible`, with a `remediation_url`).
Status 502 GitHub could not return the checks.
Status 503 The GitHub egress budget is temporarily unavailable.
Retrieve signals report pr
Fetch the pull request's conversation comments and inline review comments, merged chronologically, via the team's GitHub integration.
Required API key scopes
inbox:readPath parameters
- idstring
Query parameters
- pull_request_idstring
Response
Example request
GET /api /projects /:project_id /signals /reports /:id /pr_commentsExample response
Status 200 Conversation and review comments on the report's implementation pull request.
Status 403 The GitHub App installation is suspended or uninstalled (code `github_installation_unavailable`).
Status 404 Report has no implementation PR, or no GitHub integration can access it (code `github_repository_inaccessible`, with a `remediation_url`).
Status 502 GitHub could not return the comments.
Status 503 The GitHub egress budget is temporarily unavailable.
Create signals report pr review comments
Post an inline review comment on the report's implementation pull request, attributed to the requesting user's own GitHub identity via their personal GitHub connection. Either replies to an existing thread (in_reply_to) or starts a new thread on a diff line (path + line).
Required API key scopes
inbox:writePath parameters
- idstring
Query parameters
- pull_request_idstring
Request parameters
- bodystring
- in_reply_tostring | null
- pathstring | null
- lineinteger | null
- side
Response
Example request
POST /api /projects /:project_id /signals /reports /:id /pr_review_commentsExample response
Status 201 The created review comment, in the normalized PR-comment shape.
Status 400 Invalid comment payload.
Status 403 Not a signed-in user, or the requesting user has no usable personal GitHub connection (reconnect GitHub).
Status 404 Report has no implementation PR, or no GitHub integration can access it.
Status 502 GitHub rejected the comment.
Status 503 The GitHub egress budget is temporarily unavailable.
Update signals report pr review comment
Required API key scopes
inbox:writePath parameters
- comment_idstring
- idstring
Query parameters
- pull_request_idstring
Request parameters
- bodystring
Response
Example request
PATCH /api /projects /:project_id /signals /reports /:id /pr_review_comments /:comment_idExample response
Status 200 The edited review comment, in the normalized PR-comment shape.
Status 403 Not a signed-in user, no usable personal GitHub connection, or not the comment's author.
Status 404 Report has no implementation PR, or the comment isn't on it.
Status 502 GitHub rejected the edit.
Status 503 The GitHub egress budget is temporarily unavailable.
Delete signals report pr review comment
Required API key scopes
inbox:writePath parameters
- comment_idstring
- idstring
Query parameters
- pull_request_idstring
Example request
DELETE /api /projects /:project_id /signals /reports /:id /pr_review_comments /:comment_idExample response
Status 204 Comment deleted.
Status 403 Not a signed-in user, no usable personal GitHub connection, or not the comment's author.
Status 404 Report has no implementation PR, or the comment isn't on it.
Status 502 GitHub rejected the delete.
Status 503 The GitHub egress budget is temporarily unavailable.
Create signals report pr review comment reactions
Required API key scopes
inbox:writePath parameters
- comment_idstring
- idstring
Query parameters
- pull_request_idstring
Request parameters
- content
Response
Example request
POST /api /projects /:project_id /signals /reports /:id /pr_review_comments /:comment_id /reactionsExample response
Status 201 The created reaction.
Status 403 Not a signed-in user, or no usable personal GitHub connection.
Status 404 Report has no implementation PR, or the comment isn't on it.
Status 502 GitHub rejected the reaction.
Status 503 The GitHub egress budget is temporarily unavailable.
Delete signals report pr review comment reaction
Required API key scopes
inbox:writePath parameters
- comment_idstring
- idstring
- reaction_idstring
Query parameters
- pull_request_idstring
Example request
DELETE /api /projects /:project_id /signals /reports /:id /pr_review_comments /:comment_id /reactions /:reaction_id




