Turns

A Turn represents one round of conversation, typically starting with a user message and finishing with an agent message. Each turn contains multiple items that stream as notifications.

Turn Object

string

Unique turn identifier (e.g., turn_456)

ThreadItem[]

Array of items in this turn

Only populated on thread/resume or thread/fork responses. For all other responses and notifications, this field is an empty array. Use item/* notifications to track items.

TurnStatus

Current turn status

inProgress - Turn is actively running
completed - Turn finished successfully
interrupted - Turn was cancelled
failed - Turn encountered an error

TurnError | null

Error details (only populated when status is failed)

Show TurnError properties

string

Human-readable error message

CodexErrorInfo

Structured error classificationCommon values:

ContextWindowExceeded
UsageLimitExceeded
HttpConnectionFailed
ResponseStreamDisconnected
Unauthorized
BadRequest
InternalServerError
Other

string

Additional error context

Start a Turn

Send user input to a thread and begin Codex generation.

Method

turn/start

Parameters

string

required

Thread ID to add the turn to

UserInput[]

required

Array of user input items

Show UserInput types

Text input:

{ "type": "text", "text": "Run tests" }

Image from URL:

{ "type": "image", "url": "https://example.com/image.png" }

Local image:

{ "type": "localImage", "path": "/tmp/screenshot.png" }

Skill invocation:

{
  "type": "skill",
  "name": "skill-creator",
  "path": "/Users/me/.codex/skills/skill-creator/SKILL.md"
}

App mention:

{
  "type": "mention",
  "name": "Demo App",
  "path": "app://demo-app"
}

string

Override working directory for this turn and subsequent turns

string

Override approval policy

SandboxPolicy

Override sandbox policy

Show SandboxPolicy types

Danger full access:

{ "type": "dangerFullAccess" }

Read-only:

{
  "type": "readOnly",
  "access": {
    "type": "fullAccess"
  }
}

Workspace write:

{
  "type": "workspaceWrite",
  "writableRoots": ["/Users/me/project"],
  "networkAccess": true
}

External sandbox:

{
  "type": "externalSandbox",
  "networkAccess": "enabled"
}

string

Override model for this turn and subsequent turns

string

Override reasoning effort (low, medium, high)

string

Override reasoning summary mode (concise, verbose)

object

JSON Schema to constrain the final assistant message (applies only to this turn)

{
  "type": "object",
  "properties": {
    "answer": { "type": "string" }
  },
  "required": ["answer"],
  "additionalProperties": false
}

Response

Turn

Initial turn object with status: "inProgress" and empty items array

Notifications

The server streams JSON-RPC notifications while the turn is running:

turn/started

Initial turn notification

{
  "method": "turn/started",
  "params": {
    "threadId": "thr_123",
    "turn": {
      "id": "turn_456",
      "status": "inProgress",
      "items": [],
      "error": null
    }
  }
}

item/* notifications

See Items for full item lifecycle

item/started - New item begins
item/agentMessage/delta - Streamed text
item/completed - Item finishes

turn/completed

Final turn notification with status

{
  "method": "turn/completed",
  "params": {
    "threadId": "thr_123",
    "turn": {
      "id": "turn_456",
      "status": "completed",
      "items": [],
      "error": null
    }
  }
}

Example: Basic Turn

{
  "method": "turn/start",
  "id": 30,
  "params": {
    "threadId": "thr_123",
    "input": [
      { "type": "text", "text": "Run tests" }
    ]
  }
}

{
  "id": 30,
  "result": {
    "turn": {
      "id": "turn_456",
      "status": "inProgress",
      "items": [],
      "error": null
    }
  }
}

Example: Invoke a Skill

Include $<skill-name> in the text input and add a skill input item.

{
  "method": "turn/start",
  "id": 33,
  "params": {
    "threadId": "thr_123",
    "input": [
      {
        "type": "text",
        "text": "$skill-creator Add a new skill for triaging flaky CI"
      },
      {
        "type": "skill",
        "name": "skill-creator",
        "path": "/Users/me/.codex/skills/skill-creator/SKILL.md"
      }
    ]
  }
}

{
  "id": 33,
  "result": {
    "turn": {
      "id": "turn_457",
      "status": "inProgress",
      "items": [],
      "error": null
    }
  }
}

Example: Invoke an App

Include $<app-slug> in text and add a mention input with app://<connector-id>.

{
  "method": "turn/start",
  "id": 34,
  "params": {
    "threadId": "thr_123",
    "input": [
      {
        "type": "text",
        "text": "$demo-app Summarize the latest updates."
      },
      {
        "type": "mention",
        "name": "Demo App",
        "path": "app://demo-app"
      }
    ]
  }
}

{
  "id": 34,
  "result": {
    "turn": {
      "id": "turn_458",
      "status": "inProgress",
      "items": [],
      "error": null
    }
  }
}

Interrupt a Turn

Cancel a running turn.

Method

turn/interrupt

Parameters

string

required

Thread ID

string

required

Turn ID to interrupt

Response

object

Empty object on success

Notifications

After interruption, the server emits turn/completed with status: "interrupted".

Example

{
  "method": "turn/interrupt",
  "id": 31,
  "params": {
    "threadId": "thr_123",
    "turnId": "turn_456"
  }
}

{
  "id": 31,
  "result": {}
}

{
  "method": "turn/completed",
  "params": {
    "threadId": "thr_123",
    "turn": {
      "id": "turn_456",
      "status": "interrupted",
      "items": [],
      "error": null
    }
  }
}

Steer a Turn

Append additional user input to a currently active turn without starting a new turn.

Method

turn/steer

Parameters

string

required

Thread ID

UserInput[]

required

Additional user input to append

string

required

Required active turn ID precondition. Fails if no active turn or ID doesn’t match.

Response

string

The active turn ID that accepted the input

Example

{
  "method": "turn/steer",
  "id": 32,
  "params": {
    "threadId": "thr_123",
    "input": [
      { "type": "text", "text": "Actually focus on failing tests first." }
    ],
    "expectedTurnId": "turn_456"
  }
}

{
  "id": 32,
  "result": {
    "turnId": "turn_456"
  }
}

Turn Notifications

Emitted when a turn beginsPayload: { threadId: string, turn: Turn }

Emitted when a turn finishes (completed, interrupted, or failed)Payload: { threadId: string, turn: Turn }

Emitted after every fileChange item with turn-level unified diffPayload: { threadId: string, turnId: string, diff: string }

Emitted when the agent shares or changes its planPayload:

{
  "threadId": "thr_123",
  "turnId": "turn_456",
  "explanation": "Breaking down the task...",
  "plan": [
    { "step": "Run tests", "status": "completed" },
    { "step": "Fix errors", "status": "inProgress" },
    { "step": "Commit changes", "status": "pending" }
  ]
}

Emitted when the backend reroutes to a different modelPayload: { threadId: string, turnId: string, fromModel: string, toModel: string, reason: string }

Emitted on mid-turn errorsPayload: { error: TurnError, willRetry: boolean, threadId: string, turnId: string }

App Server API

TypeScript SDK

Turn Object

Start a Turn

Method

Parameters

Response

Notifications

Example: Basic Turn

Example: Invoke a Skill

Example: Invoke an App

Interrupt a Turn

Method

Parameters

Response

Notifications

Example

Steer a Turn

Method

Parameters

Response

Example

Turn Notifications

Next Steps

Items

Models

​Turn Object

​Start a Turn

​Method

​Parameters

​Response

​Notifications

​Example: Basic Turn

​Example: Invoke a Skill

​Example: Invoke an App

​Interrupt a Turn

​Method

​Parameters

​Response

​Notifications

​Example

​Steer a Turn

​Method

​Parameters

​Response

​Example

​Turn Notifications

​Next Steps

Items

Models

Turn Object

Start a Turn

Method

Parameters

Response

Notifications

Example: Basic Turn

Example: Invoke a Skill

Example: Invoke an App

Interrupt a Turn

Method

Parameters

Response

Notifications

Example

Steer a Turn

Method

Parameters

Response

Example

Turn Notifications

Next Steps