# Agent: Orchestration

**Page:** api/agent/orchestration

[Download Raw Markdown](./api/agent/orchestration.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



The orchestration pipeline coordinates every agent session, tool call, and budget decision inside a workspace. This page documents the workspace-level endpoints that read configuration, stream live events, expose the full debug dump, manage the interactive questions queue, and purge all orchestration state. The four domain pages cover the lifecycle and state-transition endpoints for each subsystem:

- [Master TODO](/api/agent/orchestration/todo/) — entry lifecycle, specs, freezes
- [Executor & Budget](/api/agent/orchestration/executor-budget/) — dispatcher control, worker locks, spend tracking
- [Phases & Orchestrator Sessions](/api/agent/orchestration/phases-sessions/) — phase CRUD, phase memory, prompt dispatch
- [Vault & Import](/api/agent/orchestration/vault-import/) — portable TODO storage and cross-workspace migration

The **Master TODO** is the central state machine: every orchestrated task is an entry that transitions through creation, dispatch, execution, and resolution. The executor consumes Master TODO entries subject to budget caps and worker locks; phases and orchestrator sessions drive prompt dispatch and memory; the vault persists the TODO as a portable, importable document. The endpoints below give you a cross-cutting view of that whole pipeline — config, live event feed, tool call log, debug snapshot, human-in-the-loop questions, and full reset.

## Configuration

### `GET /api/v1/workspaces/{workspaceID}/orchestration/config`

Returns the current orchestration configuration for the workspace.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{}
```



#### SDK

```ts
const { data } = await client.agent.orchestration.getConfig({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
});
```

### `PATCH /api/v1/workspaces/{workspaceID}/orchestration/config`

Partially updates the orchestration configuration. The request body is a free-form partial update object — only the fields you include are changed.

#### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | workspaceID path parameter |


#### Request Body

The body is an open partial-update object. Any fields you supply are merged into the current config.

#### Response



```json
{}
```



#### SDK

```ts
const { data } = await client.agent.orchestration.updateConfig({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
  data: { /* partial config fields */ },
});
```

## Observability

### `GET /api/v1/workspaces/{workspaceID}/orchestration/events`

Server-Sent Events stream of every orchestration event emitted in the workspace. Supports `?since_seq=N` for reconnection.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```
event: todo.created
data: {"seq":1,"type":"todo.created","payload":{}}

event: todo.dispatched
data: {"seq":2,"type":"todo.dispatched","payload":{}}
```



#### SDK

```ts
const stream = await client.agent.orchestration.streamEvents({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
});
for await (const event of stream) {
  // event.type, event.seq, event.payload
}
```

### `GET /api/v1/workspaces/{workspaceID}/orchestration/events/connections`

Returns the number of active SSE subscribers on the orchestration events stream for the workspace.

#### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | workspaceID path parameter |


#### Response



```json
{
  "count": 3
}
```



#### SDK

```ts
const { data } = await client.agent.orchestration.getEventsConnections({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
});
console.log(`Active SSE subscribers: ${data.count}`);
```

### `GET /api/v1/workspaces/{workspaceID}/orchestration/log`

Returns a paginated, filterable log of every tool call made by orchestrated sessions. The response includes the log entries and pagination metadata.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{
  "items": [
    {
      "tool": "fs.read",
      "sessionID": "01HXYZABCDEFGHJKMNPQRSTVW",
      "callID": "call_01HXYZBROWSEFILE",
      "entryID": "entry_01HXYZREADFILE",
      "title": "Read package.json",
      "timestamp": 1717691432000,
      "duration": 142,
      "status": "ok",
      "corrections": [],
      "target": "/workspace/repo/package.json",
      "agentName": "build-agent",
      "container_id": "ctr_01HXYZ",
      "workspaceID": "ws_01HXYZABCDEFGHJKMNPQRSTVW"
    },
    {
      "tool": "net.fetch",
      "sessionID": "01HXYZABCDEFGHJKMNPQRSTVW",
      "callID": "call_01HXYZFETCHURL",
      "timestamp": 1717691438000,
      "duration": 412,
      "status": "intercepted",
      "agentName": "research-agent",
      "workspaceID": "ws_01HXYZABCDEFGHJKMNPQRSTVW"
    }
  ],
  "meta": {
    "page": 1,
    "limit": 50,
    "total": 2,
    "pages": 1
  }
}
```



#### SDK

```ts
const { data } = await client.agent.orchestration.getLog({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
});
```

### `GET /api/v1/workspaces/{workspaceID}/orchestration/log/stream`

Server-Sent Events stream of tool call log entries as they are recorded.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```
event: tool.call
data: {"tool":"fs.read","callID":"call_01HXYZBROWSEFILE","status":"ok","timestamp":1717691432000}

event: tool.call
data: {"tool":"net.fetch","callID":"call_01HXYZFETCHURL","status":"intercepted","timestamp":1717691438000}
```



#### SDK

```ts
const stream = await client.agent.orchestration.streamLog({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
});
for await (const entry of stream) {
  // entry.tool, entry.callID, entry.status, ...
}
```

### `GET /api/v1/workspaces/{workspaceID}/orchestration/debug-dump`

Exports the full orchestration debug dump for the workspace — every TODO, event, budget record, session reference, and in-memory cache needed to reconstruct the live state.

#### Parameters



| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | workspaceID path parameter |


#### Response



```json
{}
```



#### SDK

```ts
const { data } = await client.agent.orchestration.getDebugDump({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
});
```

## Questions Queue

Questions are interactive prompts emitted by agents that need a human decision before they can continue — approvals, clarifications, or option picks. The queue is bounded by the number of in-flight sessions and is not paginated; answered or expired questions disappear from the feed as soon as they resolve. You can poll the list endpoint or subscribe via the orchestration events SSE stream to see new questions as they appear.

### `GET /api/v1/workspaces/{workspaceID}/orchestration/questions`

Returns every unanswered question raised by any orchestrated session in the workspace.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{
  "questions": [
    {
      "id": "que_01HXYZABCDEFGHJKMNPQRSTVW",
      "sessionID": "01HXYZABCDEFGHJKMNPQRSTVW",
      "questions": [
        {
          "question": "Which deployment target should I use for the new service?",
          "header": "Deploy target",
          "options": [
            {
              "label": "AWS us-east-1",
              "description": "Production-grade region with full feature parity."
            },
            {
              "label": "GCP europe-west1",
              "description": "Lower latency for EU users; some services are stubs."
            }
          ],
          "multiple": false,
          "custom": true
        }
      ],
      "tool": {
        "messageID": "msg_01HXYZMESSAGEID",
        "callID": "call_01HXYZCALLID"
      }
    }
  ]
}
```



#### SDK

```ts
const { data } = await client.agent.orchestration.questionsList({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
});
```

### `GET /api/v1/workspaces/{workspaceID}/orchestration/questions/{questionID}`

Returns the full detail of a single pending question, including its options and the originating tool call reference.

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |
| `questionID` | path | string | Yes | Question identifier |

#### Response



```json
{
  "question": {
    "id": "que_01HXYZABCDEFGHJKMNPQRSTVW",
    "sessionID": "01HXYZABCDEFGHJKMNPQRSTVW",
    "questions": [
      {
        "question": "Approve the schema migration on the production database?",
        "header": "Approve migration",
        "options": [
          {
            "label": "Approve",
            "description": "Run the migration now and proceed."
          },
          {
            "label": "Reject",
            "description": "Cancel and roll back the orchestrator."
          }
        ],
        "multiple": false,
        "custom": true
      }
    ],
    "tool": {
      "messageID": "msg_01HXYZMESSAGEID",
      "callID": "call_01HXYZCALLID"
    }
  }
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Question que_01HXYZABCDEFGHJKMNPQRSTVW not found"
  }
}
```



#### SDK

```ts
const { data } = await client.agent.orchestration.questionsGetDetail({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
  questionID: "que_01HXYZABCDEFGHJKMNPQRSTVW",
});
```

### `POST /api/v1/workspaces/{workspaceID}/orchestration/questions/{questionID}/answer`

Submits an answer to a pending question. The answer is an array of arrays of strings, one inner array per question in the request (questions can be multi-select).

#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |
| `questionID` | path | string | Yes | Question identifier |

#### Request Body

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `answers` | array | Yes | One inner array of selected option labels per question in the request |

```json
{
  "answers": [
    ["Approve"]
  ]
}
```

#### Response



```json
{
  "answered": true
}
```


```json
{
  "name": "NotFoundError",
  "data": {
    "message": "Question que_01HXYZABCDEFGHJKMNPQRSTVW not found"
  }
}
```



#### SDK

```ts
const { data } = await client.agent.orchestration.questionsAnswer({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
  questionID: "que_01HXYZABCDEFGHJKMNPQRSTVW",
  data: {
    answers: [["Approve"]],
  },
});
```

## Maintenance

### `POST /api/v1/workspaces/{workspaceID}/orchestration/purge`

Pauses the executor and clears every piece of orchestration state for the workspace: TODO entries, events, budgets, tool logs, session IDs, and in-memory caches. **Configuration is preserved.** Use this for a clean reset without losing your tuning.


This operation is destructive and cannot be undone. All in-flight sessions and pending questions for the workspace will be lost.


#### Parameters

| Name | In | Type | Required | Description |
|------|-----|------|----------|-------------|
| `workspaceID` | path | string | Yes | Workspace identifier |

#### Response



```json
{
  "purged": [
    "todos",
    "events",
    "budgets",
    "tool_logs",
    "session_ids",
    "caches"
  ]
}
```



#### SDK

```ts
const { data } = await client.agent.orchestration.purge({
  workspaceID: "ws_01HXYZABCDEFGHJKMNPQRSTVW",
});
console.log("Cleared:", data.purged);
```