> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/pingdotgg/t3code/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestration API

> Command and query interface for managing projects, threads, and AI sessions

## Overview

The Orchestration API provides the core command/event architecture for T3 Code. It follows event sourcing principles where commands are dispatched, domain events are persisted, and read models are projected from the event stream.

## Architecture

```mermaid theme={null}
graph LR
    A[Client] -->|dispatchCommand| B[Orchestration Engine]
    B -->|Persist Events| C[Event Store]
    C -->|Project Events| D[Read Model]
    D -->|getSnapshot| A
    C -->|Push Events| A
```

## Available Methods

All orchestration methods use the `orchestration.*` namespace:

<ParamField path="orchestration.getSnapshot" type="method">
  Retrieve the current read model snapshot
</ParamField>

<ParamField path="orchestration.dispatchCommand" type="method">
  Execute a command (create/update/delete operations)
</ParamField>

<ParamField path="orchestration.getTurnDiff" type="method">
  Get git diff for a specific turn range
</ParamField>

<ParamField path="orchestration.getFullThreadDiff" type="method">
  Get complete diff for all turns in a thread
</ParamField>

<ParamField path="orchestration.replayEvents" type="method">
  Replay events from a specific sequence number
</ParamField>

***

## getSnapshot

Retrieve the complete current state of all projects, threads, and sessions.

### Request

```json theme={null}
{
  "id": "req-1",
  "body": {
    "_tag": "orchestration.getSnapshot"
  }
}
```

### Response

<ResponseField name="snapshotSequence" type="number" required>
  Current event sequence number
</ResponseField>

<ResponseField name="projects" type="array" required>
  Array of project entities

  <Expandable title="Project structure">
    <ResponseField name="id" type="string">
      Unique project identifier
    </ResponseField>

    <ResponseField name="title" type="string">
      Project display name
    </ResponseField>

    <ResponseField name="workspaceRoot" type="string">
      Absolute path to project directory
    </ResponseField>

    <ResponseField name="defaultModel" type="string | null">
      Default AI model (e.g., "gpt-5-codex")
    </ResponseField>

    <ResponseField name="scripts" type="array">
      Project scripts (build, test, lint, etc.)
    </ResponseField>

    <ResponseField name="createdAt" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="updatedAt" type="string">
      ISO 8601 timestamp
    </ResponseField>

    <ResponseField name="deletedAt" type="string | null">
      ISO 8601 timestamp (null if not deleted)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="threads" type="array" required>
  Array of thread entities with messages, activities, and checkpoints

  <Expandable title="Thread structure">
    <ResponseField name="id" type="string">
      Unique thread identifier
    </ResponseField>

    <ResponseField name="projectId" type="string">
      Parent project ID
    </ResponseField>

    <ResponseField name="title" type="string">
      Thread display name
    </ResponseField>

    <ResponseField name="model" type="string">
      AI model in use
    </ResponseField>

    <ResponseField name="runtimeMode" type="'approval-required' | 'full-access'">
      Permission level for the provider
    </ResponseField>

    <ResponseField name="interactionMode" type="'default' | 'plan'">
      Provider interaction style
    </ResponseField>

    <ResponseField name="messages" type="array">
      Conversation messages (user/assistant/system)
    </ResponseField>

    <ResponseField name="activities" type="array">
      Thread activity log (tool calls, approvals, errors)
    </ResponseField>

    <ResponseField name="checkpoints" type="array">
      Git checkpoint summaries for each turn
    </ResponseField>

    <ResponseField name="session" type="object | null">
      Active provider session state
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="updatedAt" type="string" required>
  Last snapshot update timestamp (ISO 8601)
</ResponseField>

### Example Response

```json theme={null}
{
  "id": "req-1",
  "result": {
    "snapshotSequence": 42,
    "projects": [
      {
        "id": "proj-123",
        "title": "my-app",
        "workspaceRoot": "/home/user/projects/my-app",
        "defaultModel": "gpt-5-codex",
        "scripts": [],
        "createdAt": "2026-03-07T10:00:00.000Z",
        "updatedAt": "2026-03-07T10:00:00.000Z",
        "deletedAt": null
      }
    ],
    "threads": [
      {
        "id": "thread-456",
        "projectId": "proj-123",
        "title": "New thread",
        "model": "gpt-5-codex",
        "runtimeMode": "full-access",
        "interactionMode": "default",
        "messages": [],
        "activities": [],
        "checkpoints": [],
        "session": null,
        "createdAt": "2026-03-07T10:05:00.000Z",
        "updatedAt": "2026-03-07T10:05:00.000Z",
        "deletedAt": null
      }
    ],
    "updatedAt": "2026-03-07T12:00:00.000Z"
  }
}
```

***

## dispatchCommand

Execute a command to modify system state. Commands are validated, processed, and result in domain events.

### Request

<ParamField path="command" type="ClientOrchestrationCommand" required>
  Command object with type discriminator
</ParamField>

```json theme={null}
{
  "id": "req-2",
  "body": {
    "_tag": "orchestration.dispatchCommand",
    "command": {
      "type": "project.create",
      "commandId": "cmd-789",
      "projectId": "proj-new",
      "title": "New Project",
      "workspaceRoot": "/home/user/new-project",
      "defaultModel": "gpt-5-codex",
      "createdAt": "2026-03-07T12:00:00.000Z"
    }
  }
}
```

### Response

<ResponseField name="sequence" type="number" required>
  Event sequence number after command processing
</ResponseField>

```json theme={null}
{
  "id": "req-2",
  "result": {
    "sequence": 43
  }
}
```

### Available Commands

See [Commands](/api/commands) for the complete list of command types.

***

## getTurnDiff

Retrieve the git diff for a specific range of turns within a thread.

### Request

<ParamField path="threadId" type="string" required>
  Thread identifier
</ParamField>

<ParamField path="fromTurnCount" type="number" required>
  Starting turn number (inclusive)
</ParamField>

<ParamField path="toTurnCount" type="number" required>
  Ending turn number (inclusive). Must be ≥ fromTurnCount.
</ParamField>

```json theme={null}
{
  "id": "req-3",
  "body": {
    "_tag": "orchestration.getTurnDiff",
    "threadId": "thread-456",
    "fromTurnCount": 0,
    "toTurnCount": 2
  }
}
```

### Response

<ResponseField name="threadId" type="string" required>
  Thread identifier
</ResponseField>

<ResponseField name="fromTurnCount" type="number" required>
  Starting turn number
</ResponseField>

<ResponseField name="toTurnCount" type="number" required>
  Ending turn number
</ResponseField>

<ResponseField name="diff" type="string" required>
  Unified diff format showing file changes
</ResponseField>

```json theme={null}
{
  "id": "req-3",
  "result": {
    "threadId": "thread-456",
    "fromTurnCount": 0,
    "toTurnCount": 2,
    "diff": "diff --git a/src/index.ts b/src/index.ts\nindex 1234567..abcdefg 100644\n--- a/src/index.ts\n+++ b/src/index.ts\n@@ -1,3 +1,4 @@\n+import express from 'express';\n console.log('Hello');\n"
  }
}
```

***

## getFullThreadDiff

Retrieve the complete diff for all turns in a thread from turn 0 to the specified turn.

### Request

<ParamField path="threadId" type="string" required>
  Thread identifier
</ParamField>

<ParamField path="toTurnCount" type="number" required>
  Final turn number (inclusive)
</ParamField>

```json theme={null}
{
  "id": "req-4",
  "body": {
    "_tag": "orchestration.getFullThreadDiff",
    "threadId": "thread-456",
    "toTurnCount": 5
  }
}
```

### Response

Same structure as `getTurnDiff`, with `fromTurnCount` always set to 0.

***

## replayEvents

Replay all events after a specific sequence number. Useful for rebuilding read models or catching up after reconnection.

### Request

<ParamField path="fromSequenceExclusive" type="number" required>
  Start replaying after this sequence number (exclusive)
</ParamField>

```json theme={null}
{
  "id": "req-5",
  "body": {
    "_tag": "orchestration.replayEvents",
    "fromSequenceExclusive": 42
  }
}
```

### Response

<ResponseField name="result" type="array" required>
  Array of OrchestrationEvent objects in sequence order
</ResponseField>

```json theme={null}
{
  "id": "req-5",
  "result": [
    {
      "sequence": 43,
      "eventId": "evt-123",
      "aggregateKind": "thread",
      "aggregateId": "thread-456",
      "type": "thread.created",
      "occurredAt": "2026-03-07T12:00:00.000Z",
      "commandId": "cmd-789",
      "causationEventId": null,
      "correlationId": "cmd-789",
      "metadata": {},
      "payload": {
        "threadId": "thread-456",
        "projectId": "proj-123",
        "title": "New thread",
        "model": "gpt-5-codex",
        "runtimeMode": "full-access",
        "interactionMode": "default",
        "createdAt": "2026-03-07T12:00:00.000Z",
        "updatedAt": "2026-03-07T12:00:00.000Z"
      }
    }
  ]
}
```

***

## Source Code References

Orchestration implementation:

* **Schemas**: `packages/contracts/src/orchestration.ts`
* **Engine**: `apps/server/src/orchestration/Services/OrchestrationEngine.ts`
* **Read Model**: `apps/server/src/orchestration/Services/ProjectionSnapshotQuery.ts`
* **Reactor**: `apps/server/src/orchestration/Services/OrchestrationReactor.ts`
* **WebSocket Router**: `apps/server/src/wsServer.ts:684-714`

## Domain Model

The orchestration domain is split into two aggregate roots:

<Card title="Project Aggregate" icon="folder">
  Manages project metadata, workspace root, default model, and scripts
</Card>

<Card title="Thread Aggregate" icon="comments">
  Manages conversation threads, messages, activities, checkpoints, and provider sessions
</Card>

## Event Sourcing Flow

1. **Client dispatches command** via `dispatchCommand`
2. **Server validates command** against schema
3. **Command handler** processes business logic
4. **Domain events** are persisted to event store
5. **Read model** is updated via projection
6. **Events are broadcast** to all connected clients via push
7. **Client updates UI** based on events

## Next Steps

<CardGroup cols={2}>
  <Card title="Commands" icon="terminal" href="/api/commands">
    Explore all available command types
  </Card>

  <Card title="Events" icon="bolt" href="/api/events">
    Learn about domain event types
  </Card>

  <Card title="WebSocket Protocol" icon="network-wired" href="/api/websocket-protocol">
    Understand the transport layer
  </Card>
</CardGroup>