Files
codex/codex-rs/app-server-protocol/schema/json/v2/ThreadListResponse.json
David de Regt eaf78e43f2 Add sorting/backwardsCursor to thread/list and new thread/turns/list api (#17305)
To improve performance of UI loads from the app, add two main
improvements:
1. The `thread/list` api now gets a `sortDirection` request field and a
`backwardsCursor` to the response, which lets you paginate forwards and
backwards from a window. This lets you fetch the first few items to
display immediately while you paginate to fill in history, then can
paginate "backwards" on future loads to catch up with any changes since
the last UI load without a full reload of the entire data set.
2. Added a new `thread/turns/list` api which also has sortDirection and
backwardsCursor for the same behavior as `thread/list`, allowing you the
same small-fetch for immediate display followed by background fill-in
and resync catchup.
2026-04-17 11:49:02 -07:00

1982 lines
48 KiB
JSON

{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"AbsolutePathBuf": {
"description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
"type": "string"
},
"AgentPath": {
"type": "string"
},
"ByteRange": {
"properties": {
"end": {
"format": "uint",
"minimum": 0.0,
"type": "integer"
},
"start": {
"format": "uint",
"minimum": 0.0,
"type": "integer"
}
},
"required": [
"end",
"start"
],
"type": "object"
},
"CodexErrorInfo": {
"description": "This translation layer make sure that we expose codex error code in camel case.\n\nWhen an upstream HTTP status is available (for example, from the Responses API or a provider), it is forwarded in `httpStatusCode` on the relevant `codexErrorInfo` variant.",
"oneOf": [
{
"enum": [
"contextWindowExceeded",
"usageLimitExceeded",
"serverOverloaded",
"internalServerError",
"unauthorized",
"badRequest",
"threadRollbackFailed",
"sandboxError",
"other"
],
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"httpConnectionFailed": {
"properties": {
"httpStatusCode": {
"format": "uint16",
"minimum": 0.0,
"type": [
"integer",
"null"
]
}
},
"type": "object"
}
},
"required": [
"httpConnectionFailed"
],
"title": "HttpConnectionFailedCodexErrorInfo",
"type": "object"
},
{
"additionalProperties": false,
"description": "Failed to connect to the response SSE stream.",
"properties": {
"responseStreamConnectionFailed": {
"properties": {
"httpStatusCode": {
"format": "uint16",
"minimum": 0.0,
"type": [
"integer",
"null"
]
}
},
"type": "object"
}
},
"required": [
"responseStreamConnectionFailed"
],
"title": "ResponseStreamConnectionFailedCodexErrorInfo",
"type": "object"
},
{
"additionalProperties": false,
"description": "The response SSE stream disconnected in the middle of a turn before completion.",
"properties": {
"responseStreamDisconnected": {
"properties": {
"httpStatusCode": {
"format": "uint16",
"minimum": 0.0,
"type": [
"integer",
"null"
]
}
},
"type": "object"
}
},
"required": [
"responseStreamDisconnected"
],
"title": "ResponseStreamDisconnectedCodexErrorInfo",
"type": "object"
},
{
"additionalProperties": false,
"description": "Reached the retry limit for responses.",
"properties": {
"responseTooManyFailedAttempts": {
"properties": {
"httpStatusCode": {
"format": "uint16",
"minimum": 0.0,
"type": [
"integer",
"null"
]
}
},
"type": "object"
}
},
"required": [
"responseTooManyFailedAttempts"
],
"title": "ResponseTooManyFailedAttemptsCodexErrorInfo",
"type": "object"
},
{
"additionalProperties": false,
"description": "Returned when `turn/start` or `turn/steer` is submitted while the current active turn cannot accept same-turn steering, for example `/review` or manual `/compact`.",
"properties": {
"activeTurnNotSteerable": {
"properties": {
"turnKind": {
"$ref": "#/definitions/NonSteerableTurnKind"
}
},
"required": [
"turnKind"
],
"type": "object"
}
},
"required": [
"activeTurnNotSteerable"
],
"title": "ActiveTurnNotSteerableCodexErrorInfo",
"type": "object"
}
]
},
"CollabAgentState": {
"properties": {
"message": {
"type": [
"string",
"null"
]
},
"status": {
"$ref": "#/definitions/CollabAgentStatus"
}
},
"required": [
"status"
],
"type": "object"
},
"CollabAgentStatus": {
"enum": [
"pendingInit",
"running",
"interrupted",
"completed",
"errored",
"shutdown",
"notFound"
],
"type": "string"
},
"CollabAgentTool": {
"enum": [
"spawnAgent",
"sendInput",
"resumeAgent",
"wait",
"closeAgent"
],
"type": "string"
},
"CollabAgentToolCallStatus": {
"enum": [
"inProgress",
"completed",
"failed"
],
"type": "string"
},
"CommandAction": {
"oneOf": [
{
"properties": {
"command": {
"type": "string"
},
"name": {
"type": "string"
},
"path": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": {
"enum": [
"read"
],
"title": "ReadCommandActionType",
"type": "string"
}
},
"required": [
"command",
"name",
"path",
"type"
],
"title": "ReadCommandAction",
"type": "object"
},
{
"properties": {
"command": {
"type": "string"
},
"path": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"listFiles"
],
"title": "ListFilesCommandActionType",
"type": "string"
}
},
"required": [
"command",
"type"
],
"title": "ListFilesCommandAction",
"type": "object"
},
{
"properties": {
"command": {
"type": "string"
},
"path": {
"type": [
"string",
"null"
]
},
"query": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"search"
],
"title": "SearchCommandActionType",
"type": "string"
}
},
"required": [
"command",
"type"
],
"title": "SearchCommandAction",
"type": "object"
},
{
"properties": {
"command": {
"type": "string"
},
"type": {
"enum": [
"unknown"
],
"title": "UnknownCommandActionType",
"type": "string"
}
},
"required": [
"command",
"type"
],
"title": "UnknownCommandAction",
"type": "object"
}
]
},
"CommandExecutionSource": {
"enum": [
"agent",
"userShell",
"unifiedExecStartup",
"unifiedExecInteraction"
],
"type": "string"
},
"CommandExecutionStatus": {
"enum": [
"inProgress",
"completed",
"failed",
"declined"
],
"type": "string"
},
"DynamicToolCallOutputContentItem": {
"oneOf": [
{
"properties": {
"text": {
"type": "string"
},
"type": {
"enum": [
"inputText"
],
"title": "InputTextDynamicToolCallOutputContentItemType",
"type": "string"
}
},
"required": [
"text",
"type"
],
"title": "InputTextDynamicToolCallOutputContentItem",
"type": "object"
},
{
"properties": {
"imageUrl": {
"type": "string"
},
"type": {
"enum": [
"inputImage"
],
"title": "InputImageDynamicToolCallOutputContentItemType",
"type": "string"
}
},
"required": [
"imageUrl",
"type"
],
"title": "InputImageDynamicToolCallOutputContentItem",
"type": "object"
}
]
},
"DynamicToolCallStatus": {
"enum": [
"inProgress",
"completed",
"failed"
],
"type": "string"
},
"FileUpdateChange": {
"properties": {
"diff": {
"type": "string"
},
"kind": {
"$ref": "#/definitions/PatchChangeKind"
},
"path": {
"type": "string"
}
},
"required": [
"diff",
"kind",
"path"
],
"type": "object"
},
"GitInfo": {
"properties": {
"branch": {
"type": [
"string",
"null"
]
},
"originUrl": {
"type": [
"string",
"null"
]
},
"sha": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"HookPromptFragment": {
"properties": {
"hookRunId": {
"type": "string"
},
"text": {
"type": "string"
}
},
"required": [
"hookRunId",
"text"
],
"type": "object"
},
"McpToolCallError": {
"properties": {
"message": {
"type": "string"
}
},
"required": [
"message"
],
"type": "object"
},
"McpToolCallResult": {
"properties": {
"_meta": true,
"content": {
"items": true,
"type": "array"
},
"structuredContent": true
},
"required": [
"content"
],
"type": "object"
},
"McpToolCallStatus": {
"enum": [
"inProgress",
"completed",
"failed"
],
"type": "string"
},
"MemoryCitation": {
"properties": {
"entries": {
"items": {
"$ref": "#/definitions/MemoryCitationEntry"
},
"type": "array"
},
"threadIds": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"entries",
"threadIds"
],
"type": "object"
},
"MemoryCitationEntry": {
"properties": {
"lineEnd": {
"format": "uint32",
"minimum": 0.0,
"type": "integer"
},
"lineStart": {
"format": "uint32",
"minimum": 0.0,
"type": "integer"
},
"note": {
"type": "string"
},
"path": {
"type": "string"
}
},
"required": [
"lineEnd",
"lineStart",
"note",
"path"
],
"type": "object"
},
"MessagePhase": {
"description": "Classifies an assistant message as interim commentary or final answer text.\n\nProviders do not emit this consistently, so callers must treat `None` as \"phase unknown\" and keep compatibility behavior for legacy models.",
"oneOf": [
{
"description": "Mid-turn assistant text (for example preamble/progress narration).\n\nAdditional tool calls or assistant output may follow before turn completion.",
"enum": [
"commentary"
],
"type": "string"
},
{
"description": "The assistant's terminal answer text for the current turn.",
"enum": [
"final_answer"
],
"type": "string"
}
]
},
"NonSteerableTurnKind": {
"enum": [
"review",
"compact"
],
"type": "string"
},
"PatchApplyStatus": {
"enum": [
"inProgress",
"completed",
"failed",
"declined"
],
"type": "string"
},
"PatchChangeKind": {
"oneOf": [
{
"properties": {
"type": {
"enum": [
"add"
],
"title": "AddPatchChangeKindType",
"type": "string"
}
},
"required": [
"type"
],
"title": "AddPatchChangeKind",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"delete"
],
"title": "DeletePatchChangeKindType",
"type": "string"
}
},
"required": [
"type"
],
"title": "DeletePatchChangeKind",
"type": "object"
},
{
"properties": {
"move_path": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"update"
],
"title": "UpdatePatchChangeKindType",
"type": "string"
}
},
"required": [
"type"
],
"title": "UpdatePatchChangeKind",
"type": "object"
}
]
},
"ReasoningEffort": {
"description": "See https://platform.openai.com/docs/guides/reasoning?api-mode=responses#get-started-with-reasoning",
"enum": [
"none",
"minimal",
"low",
"medium",
"high",
"xhigh"
],
"type": "string"
},
"SessionSource": {
"oneOf": [
{
"enum": [
"cli",
"vscode",
"exec",
"appServer",
"unknown"
],
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"custom": {
"type": "string"
}
},
"required": [
"custom"
],
"title": "CustomSessionSource",
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"subAgent": {
"$ref": "#/definitions/SubAgentSource"
}
},
"required": [
"subAgent"
],
"title": "SubAgentSessionSource",
"type": "object"
}
]
},
"SubAgentSource": {
"oneOf": [
{
"enum": [
"review",
"compact",
"memory_consolidation"
],
"type": "string"
},
{
"additionalProperties": false,
"properties": {
"thread_spawn": {
"properties": {
"agent_nickname": {
"default": null,
"type": [
"string",
"null"
]
},
"agent_path": {
"anyOf": [
{
"$ref": "#/definitions/AgentPath"
},
{
"type": "null"
}
],
"default": null
},
"agent_role": {
"default": null,
"type": [
"string",
"null"
]
},
"depth": {
"format": "int32",
"type": "integer"
},
"parent_thread_id": {
"$ref": "#/definitions/ThreadId"
}
},
"required": [
"depth",
"parent_thread_id"
],
"type": "object"
}
},
"required": [
"thread_spawn"
],
"title": "ThreadSpawnSubAgentSource",
"type": "object"
},
{
"additionalProperties": false,
"properties": {
"other": {
"type": "string"
}
},
"required": [
"other"
],
"title": "OtherSubAgentSource",
"type": "object"
}
]
},
"TextElement": {
"properties": {
"byteRange": {
"allOf": [
{
"$ref": "#/definitions/ByteRange"
}
],
"description": "Byte range in the parent `text` buffer that this element occupies."
},
"placeholder": {
"description": "Optional human-readable placeholder for the element, displayed in the UI.",
"type": [
"string",
"null"
]
}
},
"required": [
"byteRange"
],
"type": "object"
},
"Thread": {
"properties": {
"agentNickname": {
"description": "Optional random unique nickname assigned to an AgentControl-spawned sub-agent.",
"type": [
"string",
"null"
]
},
"agentRole": {
"description": "Optional role (agent_role) assigned to an AgentControl-spawned sub-agent.",
"type": [
"string",
"null"
]
},
"cliVersion": {
"description": "Version of the CLI that created the thread.",
"type": "string"
},
"createdAt": {
"description": "Unix timestamp (in seconds) when the thread was created.",
"format": "int64",
"type": "integer"
},
"cwd": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "Working directory captured for the thread."
},
"ephemeral": {
"description": "Whether the thread is ephemeral and should not be materialized on disk.",
"type": "boolean"
},
"forkedFromId": {
"description": "Source thread id when this thread was created by forking another thread.",
"type": [
"string",
"null"
]
},
"gitInfo": {
"anyOf": [
{
"$ref": "#/definitions/GitInfo"
},
{
"type": "null"
}
],
"description": "Optional Git metadata captured when the thread was created."
},
"id": {
"type": "string"
},
"modelProvider": {
"description": "Model provider used for this thread (for example, 'openai').",
"type": "string"
},
"name": {
"description": "Optional user-facing thread title.",
"type": [
"string",
"null"
]
},
"path": {
"description": "[UNSTABLE] Path to the thread on disk.",
"type": [
"string",
"null"
]
},
"preview": {
"description": "Usually the first user message in the thread, if available.",
"type": "string"
},
"source": {
"allOf": [
{
"$ref": "#/definitions/SessionSource"
}
],
"description": "Origin of the thread (CLI, VSCode, codex exec, codex app-server, etc.)."
},
"status": {
"allOf": [
{
"$ref": "#/definitions/ThreadStatus"
}
],
"description": "Current runtime status for the thread."
},
"turns": {
"description": "Only populated on `thread/resume`, `thread/rollback`, `thread/fork`, and `thread/read` (when `includeTurns` is true) responses. For all other responses and notifications returning a Thread, the turns field will be an empty list.",
"items": {
"$ref": "#/definitions/Turn"
},
"type": "array"
},
"updatedAt": {
"description": "Unix timestamp (in seconds) when the thread was last updated.",
"format": "int64",
"type": "integer"
}
},
"required": [
"cliVersion",
"createdAt",
"cwd",
"ephemeral",
"id",
"modelProvider",
"preview",
"source",
"status",
"turns",
"updatedAt"
],
"type": "object"
},
"ThreadActiveFlag": {
"enum": [
"waitingOnApproval",
"waitingOnUserInput"
],
"type": "string"
},
"ThreadId": {
"type": "string"
},
"ThreadItem": {
"oneOf": [
{
"properties": {
"content": {
"items": {
"$ref": "#/definitions/UserInput"
},
"type": "array"
},
"id": {
"type": "string"
},
"type": {
"enum": [
"userMessage"
],
"title": "UserMessageThreadItemType",
"type": "string"
}
},
"required": [
"content",
"id",
"type"
],
"title": "UserMessageThreadItem",
"type": "object"
},
{
"properties": {
"fragments": {
"items": {
"$ref": "#/definitions/HookPromptFragment"
},
"type": "array"
},
"id": {
"type": "string"
},
"type": {
"enum": [
"hookPrompt"
],
"title": "HookPromptThreadItemType",
"type": "string"
}
},
"required": [
"fragments",
"id",
"type"
],
"title": "HookPromptThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"memoryCitation": {
"anyOf": [
{
"$ref": "#/definitions/MemoryCitation"
},
{
"type": "null"
}
],
"default": null
},
"phase": {
"anyOf": [
{
"$ref": "#/definitions/MessagePhase"
},
{
"type": "null"
}
],
"default": null
},
"text": {
"type": "string"
},
"type": {
"enum": [
"agentMessage"
],
"title": "AgentMessageThreadItemType",
"type": "string"
}
},
"required": [
"id",
"text",
"type"
],
"title": "AgentMessageThreadItem",
"type": "object"
},
{
"description": "EXPERIMENTAL - proposed plan item content. The completed plan item is authoritative and may not match the concatenation of `PlanDelta` text.",
"properties": {
"id": {
"type": "string"
},
"text": {
"type": "string"
},
"type": {
"enum": [
"plan"
],
"title": "PlanThreadItemType",
"type": "string"
}
},
"required": [
"id",
"text",
"type"
],
"title": "PlanThreadItem",
"type": "object"
},
{
"properties": {
"content": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"id": {
"type": "string"
},
"summary": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"type": {
"enum": [
"reasoning"
],
"title": "ReasoningThreadItemType",
"type": "string"
}
},
"required": [
"id",
"type"
],
"title": "ReasoningThreadItem",
"type": "object"
},
{
"properties": {
"aggregatedOutput": {
"description": "The command's output, aggregated from stdout and stderr.",
"type": [
"string",
"null"
]
},
"command": {
"description": "The command to be executed.",
"type": "string"
},
"commandActions": {
"description": "A best-effort parsing of the command to understand the action(s) it will perform. This returns a list of CommandAction objects because a single shell command may be composed of many commands piped together.",
"items": {
"$ref": "#/definitions/CommandAction"
},
"type": "array"
},
"cwd": {
"allOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
}
],
"description": "The command's working directory."
},
"durationMs": {
"description": "The duration of the command execution in milliseconds.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"exitCode": {
"description": "The command's exit code.",
"format": "int32",
"type": [
"integer",
"null"
]
},
"id": {
"type": "string"
},
"processId": {
"description": "Identifier for the underlying PTY process (when available).",
"type": [
"string",
"null"
]
},
"source": {
"allOf": [
{
"$ref": "#/definitions/CommandExecutionSource"
}
],
"default": "agent"
},
"status": {
"$ref": "#/definitions/CommandExecutionStatus"
},
"type": {
"enum": [
"commandExecution"
],
"title": "CommandExecutionThreadItemType",
"type": "string"
}
},
"required": [
"command",
"commandActions",
"cwd",
"id",
"status",
"type"
],
"title": "CommandExecutionThreadItem",
"type": "object"
},
{
"properties": {
"changes": {
"items": {
"$ref": "#/definitions/FileUpdateChange"
},
"type": "array"
},
"id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/PatchApplyStatus"
},
"type": {
"enum": [
"fileChange"
],
"title": "FileChangeThreadItemType",
"type": "string"
}
},
"required": [
"changes",
"id",
"status",
"type"
],
"title": "FileChangeThreadItem",
"type": "object"
},
{
"properties": {
"arguments": true,
"durationMs": {
"description": "The duration of the MCP tool call in milliseconds.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"error": {
"anyOf": [
{
"$ref": "#/definitions/McpToolCallError"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"mcpAppResourceUri": {
"type": [
"string",
"null"
]
},
"result": {
"anyOf": [
{
"$ref": "#/definitions/McpToolCallResult"
},
{
"type": "null"
}
]
},
"server": {
"type": "string"
},
"status": {
"$ref": "#/definitions/McpToolCallStatus"
},
"tool": {
"type": "string"
},
"type": {
"enum": [
"mcpToolCall"
],
"title": "McpToolCallThreadItemType",
"type": "string"
}
},
"required": [
"arguments",
"id",
"server",
"status",
"tool",
"type"
],
"title": "McpToolCallThreadItem",
"type": "object"
},
{
"properties": {
"arguments": true,
"contentItems": {
"items": {
"$ref": "#/definitions/DynamicToolCallOutputContentItem"
},
"type": [
"array",
"null"
]
},
"durationMs": {
"description": "The duration of the dynamic tool call in milliseconds.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"id": {
"type": "string"
},
"status": {
"$ref": "#/definitions/DynamicToolCallStatus"
},
"success": {
"type": [
"boolean",
"null"
]
},
"tool": {
"type": "string"
},
"type": {
"enum": [
"dynamicToolCall"
],
"title": "DynamicToolCallThreadItemType",
"type": "string"
}
},
"required": [
"arguments",
"id",
"status",
"tool",
"type"
],
"title": "DynamicToolCallThreadItem",
"type": "object"
},
{
"properties": {
"agentsStates": {
"additionalProperties": {
"$ref": "#/definitions/CollabAgentState"
},
"description": "Last known status of the target agents, when available.",
"type": "object"
},
"id": {
"description": "Unique identifier for this collab tool call.",
"type": "string"
},
"model": {
"description": "Model requested for the spawned agent, when applicable.",
"type": [
"string",
"null"
]
},
"prompt": {
"description": "Prompt text sent as part of the collab tool call, when available.",
"type": [
"string",
"null"
]
},
"reasoningEffort": {
"anyOf": [
{
"$ref": "#/definitions/ReasoningEffort"
},
{
"type": "null"
}
],
"description": "Reasoning effort requested for the spawned agent, when applicable."
},
"receiverThreadIds": {
"description": "Thread ID of the receiving agent, when applicable. In case of spawn operation, this corresponds to the newly spawned agent.",
"items": {
"type": "string"
},
"type": "array"
},
"senderThreadId": {
"description": "Thread ID of the agent issuing the collab request.",
"type": "string"
},
"status": {
"allOf": [
{
"$ref": "#/definitions/CollabAgentToolCallStatus"
}
],
"description": "Current status of the collab tool call."
},
"tool": {
"allOf": [
{
"$ref": "#/definitions/CollabAgentTool"
}
],
"description": "Name of the collab tool that was invoked."
},
"type": {
"enum": [
"collabAgentToolCall"
],
"title": "CollabAgentToolCallThreadItemType",
"type": "string"
}
},
"required": [
"agentsStates",
"id",
"receiverThreadIds",
"senderThreadId",
"status",
"tool",
"type"
],
"title": "CollabAgentToolCallThreadItem",
"type": "object"
},
{
"properties": {
"action": {
"anyOf": [
{
"$ref": "#/definitions/WebSearchAction"
},
{
"type": "null"
}
]
},
"id": {
"type": "string"
},
"query": {
"type": "string"
},
"type": {
"enum": [
"webSearch"
],
"title": "WebSearchThreadItemType",
"type": "string"
}
},
"required": [
"id",
"query",
"type"
],
"title": "WebSearchThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"path": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": {
"enum": [
"imageView"
],
"title": "ImageViewThreadItemType",
"type": "string"
}
},
"required": [
"id",
"path",
"type"
],
"title": "ImageViewThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"result": {
"type": "string"
},
"revisedPrompt": {
"type": [
"string",
"null"
]
},
"savedPath": {
"anyOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
},
{
"type": "null"
}
]
},
"status": {
"type": "string"
},
"type": {
"enum": [
"imageGeneration"
],
"title": "ImageGenerationThreadItemType",
"type": "string"
}
},
"required": [
"id",
"result",
"status",
"type"
],
"title": "ImageGenerationThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"review": {
"type": "string"
},
"type": {
"enum": [
"enteredReviewMode"
],
"title": "EnteredReviewModeThreadItemType",
"type": "string"
}
},
"required": [
"id",
"review",
"type"
],
"title": "EnteredReviewModeThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"review": {
"type": "string"
},
"type": {
"enum": [
"exitedReviewMode"
],
"title": "ExitedReviewModeThreadItemType",
"type": "string"
}
},
"required": [
"id",
"review",
"type"
],
"title": "ExitedReviewModeThreadItem",
"type": "object"
},
{
"properties": {
"id": {
"type": "string"
},
"type": {
"enum": [
"contextCompaction"
],
"title": "ContextCompactionThreadItemType",
"type": "string"
}
},
"required": [
"id",
"type"
],
"title": "ContextCompactionThreadItem",
"type": "object"
}
]
},
"ThreadStatus": {
"oneOf": [
{
"properties": {
"type": {
"enum": [
"notLoaded"
],
"title": "NotLoadedThreadStatusType",
"type": "string"
}
},
"required": [
"type"
],
"title": "NotLoadedThreadStatus",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"idle"
],
"title": "IdleThreadStatusType",
"type": "string"
}
},
"required": [
"type"
],
"title": "IdleThreadStatus",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"systemError"
],
"title": "SystemErrorThreadStatusType",
"type": "string"
}
},
"required": [
"type"
],
"title": "SystemErrorThreadStatus",
"type": "object"
},
{
"properties": {
"activeFlags": {
"items": {
"$ref": "#/definitions/ThreadActiveFlag"
},
"type": "array"
},
"type": {
"enum": [
"active"
],
"title": "ActiveThreadStatusType",
"type": "string"
}
},
"required": [
"activeFlags",
"type"
],
"title": "ActiveThreadStatus",
"type": "object"
}
]
},
"Turn": {
"properties": {
"completedAt": {
"description": "Unix timestamp (in seconds) when the turn completed.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"durationMs": {
"description": "Duration between turn start and completion in milliseconds, if known.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"error": {
"anyOf": [
{
"$ref": "#/definitions/TurnError"
},
{
"type": "null"
}
],
"description": "Only populated when the Turn's status is failed."
},
"id": {
"type": "string"
},
"items": {
"description": "Only populated on a `thread/resume` or `thread/fork` response. For all other responses and notifications returning a Turn, the items field will be an empty list.",
"items": {
"$ref": "#/definitions/ThreadItem"
},
"type": "array"
},
"startedAt": {
"description": "Unix timestamp (in seconds) when the turn started.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"status": {
"$ref": "#/definitions/TurnStatus"
}
},
"required": [
"id",
"items",
"status"
],
"type": "object"
},
"TurnError": {
"properties": {
"additionalDetails": {
"default": null,
"type": [
"string",
"null"
]
},
"codexErrorInfo": {
"anyOf": [
{
"$ref": "#/definitions/CodexErrorInfo"
},
{
"type": "null"
}
]
},
"message": {
"type": "string"
}
},
"required": [
"message"
],
"type": "object"
},
"TurnStatus": {
"enum": [
"completed",
"interrupted",
"failed",
"inProgress"
],
"type": "string"
},
"UserInput": {
"oneOf": [
{
"properties": {
"text": {
"type": "string"
},
"text_elements": {
"default": [],
"description": "UI-defined spans within `text` used to render or persist special elements.",
"items": {
"$ref": "#/definitions/TextElement"
},
"type": "array"
},
"type": {
"enum": [
"text"
],
"title": "TextUserInputType",
"type": "string"
}
},
"required": [
"text",
"type"
],
"title": "TextUserInput",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"image"
],
"title": "ImageUserInputType",
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"type",
"url"
],
"title": "ImageUserInput",
"type": "object"
},
{
"properties": {
"path": {
"type": "string"
},
"type": {
"enum": [
"localImage"
],
"title": "LocalImageUserInputType",
"type": "string"
}
},
"required": [
"path",
"type"
],
"title": "LocalImageUserInput",
"type": "object"
},
{
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"type": {
"enum": [
"skill"
],
"title": "SkillUserInputType",
"type": "string"
}
},
"required": [
"name",
"path",
"type"
],
"title": "SkillUserInput",
"type": "object"
},
{
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string"
},
"type": {
"enum": [
"mention"
],
"title": "MentionUserInputType",
"type": "string"
}
},
"required": [
"name",
"path",
"type"
],
"title": "MentionUserInput",
"type": "object"
}
]
},
"WebSearchAction": {
"oneOf": [
{
"properties": {
"queries": {
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"query": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"search"
],
"title": "SearchWebSearchActionType",
"type": "string"
}
},
"required": [
"type"
],
"title": "SearchWebSearchAction",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"openPage"
],
"title": "OpenPageWebSearchActionType",
"type": "string"
},
"url": {
"type": [
"string",
"null"
]
}
},
"required": [
"type"
],
"title": "OpenPageWebSearchAction",
"type": "object"
},
{
"properties": {
"pattern": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"findInPage"
],
"title": "FindInPageWebSearchActionType",
"type": "string"
},
"url": {
"type": [
"string",
"null"
]
}
},
"required": [
"type"
],
"title": "FindInPageWebSearchAction",
"type": "object"
},
{
"properties": {
"type": {
"enum": [
"other"
],
"title": "OtherWebSearchActionType",
"type": "string"
}
},
"required": [
"type"
],
"title": "OtherWebSearchAction",
"type": "object"
}
]
}
},
"properties": {
"backwardsCursor": {
"description": "Opaque cursor to pass as `cursor` when reversing `sortDirection`. This is only populated when the page contains at least one thread. Use it with the opposite `sortDirection`; for timestamp sorts it anchors at the start of the page timestamp so same-second updates are not skipped.",
"type": [
"string",
"null"
]
},
"data": {
"items": {
"$ref": "#/definitions/Thread"
},
"type": "array"
},
"nextCursor": {
"description": "Opaque cursor to pass to the next call to continue after the last item. if None, there are no more items to return.",
"type": [
"string",
"null"
]
}
},
"required": [
"data"
],
"title": "ThreadListResponse",
"type": "object"
}