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 — entry lifecycle, specs, freezes
• Executor & Budget — dispatcher control, worker locks, spend tracking
• Phases & Orchestrator Sessions — phase CRUD, phase memory, prompt dispatch
• 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

200

{}

SDK

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

200

{}

SDK

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

200

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

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

SDK

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

200

{
  "count": 3
}

SDK

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

200

{
  "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

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

200

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

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

200

{}

SDK

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

200

{
  "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

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

200

{
  "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"
    }
  }
}

404

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

SDK

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

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

Response

200

{
  "answered": true
}

404

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

SDK

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.

Caution

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

200

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

SDK

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