# Get a run's change state

- **OpenAPI Version:** `3.2.0`
- **API Version:** `3.1.0`
- **Contact:** Syndai <https://syndai.ai>

## Contents

**Operations**

- [GET /api/v1/external/coding/runs/{coding\_run\_id}/change](#scalar-operation-get-apiv1externalcodingrunscoding-run-idchange)

**Schemas**

- [ChangeStateResponse](#scalar-schema-changestateresponse)
- [ChangeHeldRead](#scalar-schema-changeheldread)
- [ChangeQuestionRead](#scalar-schema-changequestionread)
- [ExternalCodingHitlInputRead](#scalar-schema-externalcodinghitlinputread)
- [ExternalCodingHitlFreeTextPolicyRead](#scalar-schema-externalcodinghitlfreetextpolicyread)
- [ExternalCodingHitlOptionRead](#scalar-schema-externalcodinghitloptionread)
- [ChangeProjectRead](#scalar-schema-changeprojectread)
- [ProblemDetail](#scalar-schema-problemdetail)
- [ExternalErrorCode](#scalar-schema-externalerrorcode)

<a id="scalar-context-global-servers"></a>

## Servers

- **URL:** `https://api.syndai.ai`

<a id="scalar-context-global-authentication"></a>

## Authentication

- **CustomerApiKey**: HTTP bearer (`API Key`)

  Customer API key sent as a bearer token

## Tags

### Runs

A run is one coding task Syndai carries from a prompt to a delivered change. Creating a run starts billable work; its `external_request_id` is the idempotency key, so a retry never starts a second run. Follow a run by streaming its events or polling `GET /runs/{id}`. Phases are open-ended: a run can pause to ask you something, so read `pending_hitl_requests` and answer through `/responses` rather than assuming a fixed order.

## Operations

<a id="scalar-operation-get-apiv1externalcodingrunscoding-run-idchange"></a>

### Get a run's change state

- **Method:** `GET`
- **Path:** `/api/v1/external/coding/runs/{coding_run_id}/change`
- **Operation ID:** `getChangeState`
- **Tags:** Runs

ChangeState: `state`, a server-written `headline`, the questions it waits on (`needs_input`), a hold and its `review_url`, `live_url`, `done` and the CLI's `exit_code`. Pass the last `cursor` with `wait` (seconds, at most 45) to block until something that matters changes; without a `cursor` it answers at once. It may return early, unchanged, when the server restarts: call again.

**Servers:** [Inherited servers](#scalar-context-global-servers)

**Authentication:** [Global authentication](#scalar-context-global-authentication)

#### Path parameters

- **`coding_run_id` (required)**: `string`, format: `uuid`

#### Query parameters

- **`wait`**: `integer`, default: `0`, minimum: `0`, maximum: `45`
- **`cursor`**: `string | null`, maxLength: `64`
- **`customer_id`**: `string | null`, format: `uuid`

#### Responses

##### 200 Request fulfilled, document follows

**Content type:** `application/json`

[ChangeStateResponse](#scalar-schema-changestateresponse)

<a id="scalar-example-1"></a>

**Generated example:**

```json
{
  "cursor": "",
  "done": true,
  "exit_code": 1,
  "headline": "",
  "held": {
    "can_retry": true,
    "head_sha": "",
    "message": "",
    "paths": [
      ""
    ],
    "reason": "",
    "review_url": ""
  },
  "live_url": "",
  "needs_input": [
    {
      "hitl_request_id": "",
      "inputs": [
        {
          "context": "",
          "default_assumption": "",
          "default_option_ids": [
            ""
          ],
          "free_text": {
            "enabled": true,
            "max_length": 1,
            "placeholder": "",
            "required_policy": "",
            "ui_mode": ""
          },
          "input_id": "",
          "kind": "",
          "options": [
            {
              "id": "",
              "label": ""
            }
          ],
          "prompt": "",
          "required": true
        }
      ],
      "kind": "",
      "summary": ""
    }
  ],
  "pr_url": "",
  "project": {
    "id": "",
    "live_url": "",
    "name": ""
  },
  "queue_position": 1,
  "receipt_url": "",
  "run_id": "",
  "run_url": "",
  "state": "",
  "verified": true
}
```

##### 400, 401, 403, 404, 426

- `400` Bad request syntax or unsupported method
- `401` Invalid or missing customer API key
- `403` Insufficient scope or forbidden customer access
- `404` Resource not found
- `426` CLI\_UPGRADE\_REQUIRED: run npx -y syndai\@latest

**Content type:** `application/problem+json`

[ProblemDetail](#scalar-schema-problemdetail)

RFC 7807 problem detail returned for public CaaS errors.

<a id="scalar-example-2"></a>

**Generated example:**

```json
{
  "code": "BUDGET_EXHAUSTED",
  "detail": null,
  "existing_run_id": null,
  "instance": null,
  "status": 1,
  "title": "",
  "type": "about:blank",
  "additionalProperty": "anything"
}
```

##### 429 Rate limit exceeded

**Headers:**

- **`Retry-After`**

  Seconds to wait before retrying the request

  `integer`

**Content type:** `application/problem+json`

[ProblemDetail](#scalar-schema-problemdetail)

RFC 7807 problem detail returned for public CaaS errors.

[Generated example](#scalar-example-2)

##### default Unexpected error

**Content type:** `application/problem+json`

[ProblemDetail](#scalar-schema-problemdetail)

<a id="scalar-example-3"></a>

**Generated example:**

```json
null
```

## Schemas

<a id="scalar-schema-changestateresponse"></a>

### ChangeStateResponse

**Type:** `object`

- **`cursor` (required)**: `string`
- **`done` (required)**: `boolean`
- **`headline` (required)**: `string`
- **`needs_input` (required)**: array of [ChangeQuestionRead](#scalar-schema-changequestionread)
- **`project` (required)**: [ChangeProjectRead](#scalar-schema-changeprojectread)
- **`run_id` (required)**: `string`, format: `uuid`
- **`run_url` (required)**: `string`
- **`state` (required)**: `string`
- **`exit_code`**: `integer | null`
- **`held`**: [ChangeHeldRead](#scalar-schema-changeheldread) | `null`
- **`live_url`**: `string | null`
- **`pr_url`**: `string | null`
- **`queue_position`**: `integer | null`
- **`receipt_url`**: `string | null`
- **`verified`**: `boolean | null`

<a id="scalar-example-4"></a>

**Generated example:**

```json
{
  "cursor": "",
  "done": true,
  "exit_code": 1,
  "headline": "",
  "held": {
    "can_retry": true,
    "head_sha": "",
    "message": "",
    "paths": [
      ""
    ],
    "reason": "",
    "review_url": ""
  },
  "live_url": "",
  "needs_input": [
    {
      "hitl_request_id": "",
      "inputs": [
        {
          "context": "",
          "default_assumption": "",
          "default_option_ids": [
            ""
          ],
          "free_text": {
            "enabled": true,
            "max_length": 1,
            "placeholder": "",
            "required_policy": "",
            "ui_mode": ""
          },
          "input_id": "",
          "kind": "",
          "options": [
            {
              "id": "",
              "label": ""
            }
          ],
          "prompt": "",
          "required": true
        }
      ],
      "kind": "",
      "summary": ""
    }
  ],
  "pr_url": "",
  "project": {
    "id": "",
    "live_url": "",
    "name": ""
  },
  "queue_position": 1,
  "receipt_url": "",
  "run_id": "",
  "run_url": "",
  "state": "",
  "verified": true
}
```

<a id="scalar-schema-changeheldread"></a>

### ChangeHeldRead

**Type:** `object`

- **`can_retry` (required)**: `boolean`
- **`message` (required)**: `string`
- **`paths` (required)**: `array of string`
- **`review_url` (required)**: `string`
- **`head_sha`**: `string | null`
- **`reason`**: `string | null`

<a id="scalar-example-5"></a>

**Generated example:**

```json
{
  "can_retry": true,
  "head_sha": "",
  "message": "",
  "paths": [
    ""
  ],
  "reason": "",
  "review_url": ""
}
```

<a id="scalar-schema-changequestionread"></a>

### ChangeQuestionRead

**Type:** `object`

- **`hitl_request_id` (required)**: `string`, format: `uuid`
- **`inputs` (required)**: array of [ExternalCodingHitlInputRead](#scalar-schema-externalcodinghitlinputread)
- **`kind` (required)**: `string`
- **`summary` (required)**: `string`

<a id="scalar-example-6"></a>

**Generated example:**

```json
{
  "hitl_request_id": "",
  "inputs": [
    {
      "context": "",
      "default_assumption": "",
      "default_option_ids": [
        ""
      ],
      "free_text": {
        "enabled": true,
        "max_length": 1,
        "placeholder": "",
        "required_policy": "",
        "ui_mode": ""
      },
      "input_id": "",
      "kind": "",
      "options": [
        {
          "id": "",
          "label": ""
        }
      ],
      "prompt": "",
      "required": true
    }
  ],
  "kind": "",
  "summary": ""
}
```

<a id="scalar-schema-externalcodinghitlinputread"></a>

### ExternalCodingHitlInputRead

**Type:** `object`

- **`input_id` (required)**: `string`
- **`kind` (required)**: `string`
- **`prompt` (required)**: `string`
- **`required` (required)**: `boolean`
- **`context`**: `string | null`
- **`default_assumption`**: `string | null`
- **`default_option_ids`**: `array of string`
- **`free_text`**: [ExternalCodingHitlFreeTextPolicyRead](#scalar-schema-externalcodinghitlfreetextpolicyread) | `null`
- **`options`**: array of [ExternalCodingHitlOptionRead](#scalar-schema-externalcodinghitloptionread)

<a id="scalar-example-7"></a>

**Generated example:**

```json
{
  "context": "",
  "default_assumption": "",
  "default_option_ids": [
    ""
  ],
  "free_text": {
    "enabled": true,
    "max_length": 1,
    "placeholder": "",
    "required_policy": "",
    "ui_mode": ""
  },
  "input_id": "",
  "kind": "",
  "options": [
    {
      "id": "",
      "label": ""
    }
  ],
  "prompt": "",
  "required": true
}
```

<a id="scalar-schema-externalcodinghitlfreetextpolicyread"></a>

### ExternalCodingHitlFreeTextPolicyRead

**Type:** `object`

- **`enabled` (required)**: `boolean`
- **`max_length`**: `integer | null`
- **`placeholder`**: `string | null`
- **`required_policy`**: `string | null`
- **`ui_mode`**: `string | null`

<a id="scalar-example-8"></a>

**Generated example:**

```json
{
  "enabled": true,
  "max_length": 1,
  "placeholder": "",
  "required_policy": "",
  "ui_mode": ""
}
```

<a id="scalar-schema-externalcodinghitloptionread"></a>

### ExternalCodingHitlOptionRead

**Type:** `object`

- **`id` (required)**: `string`
- **`label` (required)**: `string`

<a id="scalar-example-9"></a>

**Generated example:**

```json
{
  "id": "",
  "label": ""
}
```

<a id="scalar-schema-changeprojectread"></a>

### ChangeProjectRead

**Type:** `object`

- **`id` (required)**: `string`, format: `uuid`
- **`name` (required)**: `string`
- **`live_url`**: `string | null`

<a id="scalar-example-10"></a>

**Generated example:**

```json
{
  "id": "",
  "live_url": "",
  "name": ""
}
```

<a id="scalar-schema-problemdetail"></a>

### ProblemDetail

**Type:** `object`

RFC 7807 problem detail returned for public CaaS errors.

- **`code` (required)**: `string`, possible values: `"BUDGET_EXHAUSTED", "QUOTA_EXCEEDED", "RUN_CONCURRENCY_LIMIT", "CUSTOMER_DISABLED", "REPO_NOT_BOUND", "IDEMPOTENCY_REPLAY", "CONFLICT", "MISSION_BUSY_RETRY", "HITL_REQUEST_CONFLICT", "HITL_REQUEST_SETTLED", "RUN_TERMINATED_BEFORE_RESPONSE", "INVALID_POLICY", "INVALID_SCOPE", "RATE_LIMITED", "INSTALLATION_INCOMPLETE", "SUBSCRIPTION_USAGE_UNAVAILABLE", "INVALID_TOKEN", "ROLE_REQUIRED", "PLAN_UPGRADE_REQUIRED", "EMAIL_MISMATCH", "EXPIRED_TOKEN", "NOT_FOUND", "OVERSCOPE_ACK_REQUIRED", "VERIFY_FAILED", "PUBLISH_IN_FLIGHT", "PUBLISH_UNSUPPORTED_REPO", "PUBLICATION_NOT_LIVE", "NO_APP_DATA", "FEATURE_REQUESTS_NEEDS_MEMBERS", "EMPTY_UPDATE", "BAD_CURSOR", "HUMAN_APPROVAL_REQUIRED", "PROTECTED_PATHS_MANAGED_ONLY", "RUN_IN_FLIGHT", "TEXT_EDIT_REFUSED", "CLI_UPGRADE_REQUIRED", "PRODUCTION_STEP_UP_REQUIRED", "PRICES_UPDATING", "GITHUB_UNAVAILABLE", "PUBLISH_NOT_SET_UP", "VERSION_NOT_DEPLOYED", "INTERNAL_ERROR"`

  Stable error codes surfaced to public CaaS clients.
- **`status` (required)**: `integer`
- **`title` (required)**: `string`
- **`detail`**: `string | null`, default: `null`
- **`existing_run_id`**: `string | null`, default: `null`
- **`instance`**: `string | null`, default: `null`
- **`type`**: `string`, default: `"about:blank"`

<a id="scalar-example-11"></a>

**Generated example:**

```json
{
  "code": "BUDGET_EXHAUSTED",
  "detail": null,
  "existing_run_id": null,
  "instance": null,
  "status": 1,
  "title": "",
  "type": "about:blank",
  "additionalProperty": "anything"
}
```

<a id="scalar-schema-externalerrorcode"></a>

### ExternalErrorCode

**Type:** `string`, possible values: `"BUDGET_EXHAUSTED", "QUOTA_EXCEEDED", "RUN_CONCURRENCY_LIMIT", "CUSTOMER_DISABLED", "REPO_NOT_BOUND", "IDEMPOTENCY_REPLAY", "CONFLICT", "MISSION_BUSY_RETRY", "HITL_REQUEST_CONFLICT", "HITL_REQUEST_SETTLED", "RUN_TERMINATED_BEFORE_RESPONSE", "INVALID_POLICY", "INVALID_SCOPE", "RATE_LIMITED", "INSTALLATION_INCOMPLETE", "SUBSCRIPTION_USAGE_UNAVAILABLE", "INVALID_TOKEN", "ROLE_REQUIRED", "PLAN_UPGRADE_REQUIRED", "EMAIL_MISMATCH", "EXPIRED_TOKEN", "NOT_FOUND", "OVERSCOPE_ACK_REQUIRED", "VERIFY_FAILED", "PUBLISH_IN_FLIGHT", "PUBLISH_UNSUPPORTED_REPO", "PUBLICATION_NOT_LIVE", "NO_APP_DATA", "FEATURE_REQUESTS_NEEDS_MEMBERS", "EMPTY_UPDATE", "BAD_CURSOR", "HUMAN_APPROVAL_REQUIRED", "PROTECTED_PATHS_MANAGED_ONLY", "RUN_IN_FLIGHT", "TEXT_EDIT_REFUSED", "CLI_UPGRADE_REQUIRED", "PRODUCTION_STEP_UP_REQUIRED", "PRICES_UPDATING", "GITHUB_UNAVAILABLE", "PUBLISH_NOT_SET_UP", "VERSION_NOT_DEPLOYED", "INTERNAL_ERROR"`

Stable error codes surfaced to public CaaS clients.