Syndai Docs

Request changes to a run's drafted spec

POST
/api/v1/external/coding/runs/{coding_run_id}/spec/request-changes

Submits review feedback (annotations on criteria, the brief or the goal, and/or an overall comment) and queues an asynchronous revision of the spec; poll GET /runs/{id} for the next review round. Replaying the same idempotency_key records nothing twice and queues no second revision. Returns 400 for an empty or invalid batch and 409 when base_round is stale, the review is closed, the run was cancelled, or no spec has been drafted yet. Needs a signed-in person allowed to review the run (an API key gets 401, another member 403).

Authorization

CustomerApiKey
headerAuthorizationBearer <API Key>

Customer API key sent as a bearer token

Path Parameters

coding_run_id*string
Formatuuid

Query Parameters

customer_id?|null

Request Body

application/json
  1. body
annotations?array<>
base_round*integer
Range1 <= value
idempotency_key*string
Length1 <= length <= 160
overall_comment?string|null

Response Body

Request fulfilled, document follows

application/json
  1. response
activity?array<>
artifact_bundle?|null
brief?string|null
bug_scan_stats?|null
criteria?array<>
criteria_agreement?string
Default"pending"
delivered_diff_stats?|null
engineering_plan?|null
evidence?|null
final_response?|null
goal?|null
has_proposed_diff?boolean
Defaultfalse
linked_runs?array<>|null
liveness?|null
paid_by?|null
pause?|null
pending_facts?array<>
pending_hitl_requests?array<>
project*
queued?|null
review_gates?array<>
run*
session_approvals?array<>
spec_review?
spec_review_expires_at?string
spec_review_wait_until?string
steer_messages?array<>
stop_requested?boolean
Defaultfalse
tools_used?array<>
validations?array<>
Example Request
curl -X POST 'https://api.syndai.ai/api/v1/external/coding/runs/497f6eca-6276-4993-bfeb-53cbbbba6f08/spec/request-changes' \  -H 'Content-Type: application/json' \  -d '{  "base_round": 1,  "idempotency_key": "spec-review-4812-1",  "overall_comment": "Keep the toggle in the header only; no settings page."}'
Example Response
{  "has_proposed_diff": false,  "pause": null,  "pending_hitl_requests": [],  "project": {    "created_at": "2026-10-27T09:00:00Z",    "default_branch": "main",    "id": "c2e5f8a1-3b4d-4e6f-8a9b-1c2d3e4f5a6b",    "large_repo_detected": false,    "repo_name": "storefront",    "repo_owner": "acme",    "repo_url": "https://github.com/acme/storefront",    "updated_at": "2026-10-27T09:00:00Z"  },  "run": {    "artifact_retention_profile": "standard",    "autonomy_mode": "review",    "base_branch": "main",    "coding_project_id": "c2e5f8a1-3b4d-4e6f-8a9b-1c2d3e4f5a6b",    "coding_repository_id": "8a1d4e2f-5b6c-4d7e-8f9a-0b1c2d3e4f50",    "created_at": "2026-10-27T09:00:00Z",    "current_phase": "execute",    "egress_profile": "managed_default",    "external_request_id": "ticket-4812",    "id": "3f9c2b7a-6d1e-4c8b-9a2f-1b7e5d4c3a21",    "pr_url": null,    "title": "Add a dark mode toggle to the header",    "updated_at": "2026-10-27T09:04:12Z",    "validation_iteration": 0  },  "stop_requested": false}