---
title: "Report coding-agent execution status"
method: POST
path: "/api/v1/agent-runs/{id}/status"
tags: ["Execution"]
---

# Report coding-agent execution status

`POST /api/v1/agent-runs/{id}/status`

## Request

- Base URL: `https://www.specky.space`
- URL: `https://www.specky.space/api/v1/agent-runs/{id}/status`
- Auth: HTTP bearer

Agents should call this after starting work and when they have a branch, pull request, checks, blocker, or final outcome.

## Path parameters

- `id` string, uuid, required

## Request body

- object
  - `status` 'queued' | 'pending_assignment' | 'assigned' | 'awaiting_agent' | 'in_progress' | 'awaiting_review' | 'changes_requested' | 'passed' | 'failed' | 'blocked' | 'cancelled'
  - `note` string
  - `branch` string
  - `commit_sha` string
  - `pull_request_url` string, uri
  - `provider_agent_id` string
  - `provider_run_id` string
  - `checks` unknown[]
    - unknown
  - `ci_status` 'not_reported' | 'queued' | 'in_progress' | 'success' | 'failure' | 'cancelled' | 'unknown'
  - `ci_name` string, nullable
  - `ci_url` string, uri, nullable
  - `ci_conclusion` string, nullable
  - `ci_at` string, date-time, nullable
  - `deployment_status` 'not_reported' | 'queued' | 'in_progress' | 'success' | 'failure' | 'cancelled' | 'unknown'
  - `deployment_environment` string, nullable
  - `deployment_url` string, uri, nullable
  - `deployment_id` string, nullable
  - `deployment_at` string, date-time, nullable
  - `deployment_source` string, nullable
  - `production_deployment_status` 'not_reported' | 'queued' | 'in_progress' | 'success' | 'failure' | 'cancelled' | 'unknown'
  - `production_deployment_url` string, uri, nullable
  - `production_deployed_at` string, date-time, nullable
  - `smoke_test_status` 'not_reported' | 'queued' | 'in_progress' | 'success' | 'failure' | 'cancelled' | 'unknown'
  - `smoke_test_name` string, nullable
  - `smoke_test_url` string, uri, nullable
  - `smoke_test_at` string, date-time, nullable
  - `feature_flag_status` 'not_reported' | 'queued' | 'in_progress' | 'success' | 'failure' | 'cancelled' | 'unknown'
  - `feature_flag_name` string, nullable
  - `feature_flag_at` string, date-time, nullable
  - `summary` string
  - `blocked_reason` string
  - `error` string

## Response `200`

Successful response. Always includes `summary` (string) and `ok: true`; mutating endpoints additionally include the created resource id under a tool-specific key.

- OkSummary
  - `ok` true
  - `summary` string: Human-readable result text.

## Other responses

- `400`: Invalid request body or path
- `401`: Missing or invalid bearer token

---

[API](https://skmtc.dev/specky/apis/specky-api.md) · [All operations](https://skmtc.dev/specky/apis/specky-api/llms.txt) · [OpenAPI document](https://skmtc.dev/specky/apis/specky-api/revisions/bed1995f892c?raw)