> ## Documentation Index > Fetch the complete documentation index at: https://cognitio-agent.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Subscribe to events > Get events ## OpenAPI ````yaml /openapi.json get /event openapi: 3.1.1 info: title: cognitio description: cognitio api version: 1.0.0 servers: [] security: [] paths: /event: get: summary: Subscribe to events description: Get events operationId: event.subscribe parameters: - in: query name: directory schema: type: string - in: query name: workspace schema: type: string responses: '200': description: Event stream content: text/event-stream: schema: $ref: '#/components/schemas/Event' x-codeSamples: - lang: js source: |- import { createCognitioClient } from "@cognitio/sdk const client = createCognitioClient() await client.event.subscribe({ ... }) components: schemas: Event: anyOf: - $ref: '#/components/schemas/Event.project.updated' - $ref: '#/components/schemas/Event.server.instance.disposed' - $ref: '#/components/schemas/Event.server.connected' - $ref: '#/components/schemas/Event.global.disposed' - $ref: '#/components/schemas/Event.file.edited' - $ref: '#/components/schemas/Event.file.watcher.updated' - $ref: '#/components/schemas/Event.lsp.client.diagnostics' - $ref: '#/components/schemas/Event.lsp.updated' - $ref: '#/components/schemas/Event.installation.updated' - $ref: '#/components/schemas/Event.installation.update-available' - $ref: '#/components/schemas/Event.message.part.delta' - $ref: '#/components/schemas/Event.tui.prompt.append' - $ref: '#/components/schemas/Event.tui.command.execute' - $ref: '#/components/schemas/Event.tui.toast.show' - $ref: '#/components/schemas/Event.tui.session.select' - $ref: '#/components/schemas/Event.control.request' - $ref: '#/components/schemas/Event.control.cancelled' - $ref: '#/components/schemas/Event.mcp.tools.changed' - $ref: '#/components/schemas/Event.mcp.browser.open.failed' - $ref: '#/components/schemas/Event.permission.asked' - $ref: '#/components/schemas/Event.permission.replied' - $ref: '#/components/schemas/Event.session.diff' - $ref: '#/components/schemas/Event.session.error' - $ref: '#/components/schemas/Event.session.result' - $ref: '#/components/schemas/Event.subagent.started' - $ref: '#/components/schemas/Event.subagent.progress' - $ref: '#/components/schemas/Event.subagent.stopped' - $ref: '#/components/schemas/Event.session.rate_limit_hit' - $ref: '#/components/schemas/Event.task.started' - $ref: '#/components/schemas/Event.task.progress' - $ref: '#/components/schemas/Event.task.notification' - $ref: '#/components/schemas/Event.task.stopped' - $ref: '#/components/schemas/Event.session.status' - $ref: '#/components/schemas/Event.session.idle' - $ref: '#/components/schemas/Event.session.checkpoint.created' - $ref: '#/components/schemas/Event.session.rewound' - $ref: '#/components/schemas/Event.question.asked' - $ref: '#/components/schemas/Event.question.replied' - $ref: '#/components/schemas/Event.question.rejected' - $ref: '#/components/schemas/Event.session.compacted' - $ref: '#/components/schemas/Event.system.compact_boundary' - $ref: '#/components/schemas/Event.todo.updated' - $ref: '#/components/schemas/Event.command.executed' - $ref: '#/components/schemas/Event.vcs.branch.updated' - $ref: '#/components/schemas/Event.worktree.ready' - $ref: '#/components/schemas/Event.worktree.failed' - $ref: '#/components/schemas/Event.pty.created' - $ref: '#/components/schemas/Event.pty.updated' - $ref: '#/components/schemas/Event.pty.exited' - $ref: '#/components/schemas/Event.pty.deleted' - $ref: '#/components/schemas/Event.workspace.ready' - $ref: '#/components/schemas/Event.workspace.failed' - $ref: '#/components/schemas/Event.workspace.restore' - $ref: '#/components/schemas/Event.workspace.status' - $ref: '#/components/schemas/Event.message.updated' - $ref: '#/components/schemas/Event.message.removed' - $ref: '#/components/schemas/Event.message.part.updated' - $ref: '#/components/schemas/Event.message.part.removed' - $ref: '#/components/schemas/Event.session.created' - $ref: '#/components/schemas/Event.session.updated' - $ref: '#/components/schemas/Event.session.deleted' Event.project.updated: type: object properties: type: type: string const: project.updated properties: $ref: '#/components/schemas/Project' required: - type - properties Event.server.instance.disposed: type: object properties: type: type: string const: server.instance.disposed properties: type: object properties: directory: type: string required: - directory required: - type - properties Event.server.connected: type: object properties: type: type: string const: server.connected properties: type: object properties: {} required: - type - properties Event.global.disposed: type: object properties: type: type: string const: global.disposed properties: type: object properties: {} required: - type - properties Event.file.edited: type: object properties: type: type: string const: file.edited properties: type: object properties: file: type: string required: - file required: - type - properties Event.file.watcher.updated: type: object properties: type: type: string const: file.watcher.updated properties: type: object properties: file: type: string event: anyOf: - type: string const: add - type: string const: change - type: string const: unlink required: - file - event required: - type - properties Event.lsp.client.diagnostics: type: object properties: type: type: string const: lsp.client.diagnostics properties: type: object properties: serverID: type: string path: type: string required: - serverID - path required: - type - properties Event.lsp.updated: type: object properties: type: type: string const: lsp.updated properties: type: object properties: {} required: - type - properties Event.installation.updated: type: object properties: type: type: string const: installation.updated properties: type: object properties: version: type: string required: - version required: - type - properties Event.installation.update-available: type: object properties: type: type: string const: installation.update-available properties: type: object properties: version: type: string required: - version required: - type - properties Event.message.part.delta: type: object properties: type: type: string const: message.part.delta properties: type: object properties: sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* partID: type: string pattern: ^prt.* field: type: string delta: type: string required: - sessionID - messageID - partID - field - delta required: - type - properties Event.tui.prompt.append: type: object properties: type: type: string const: tui.prompt.append properties: type: object properties: text: type: string required: - text required: - type - properties Event.tui.command.execute: type: object properties: type: type: string const: tui.command.execute properties: type: object properties: command: anyOf: - type: string enum: - session.list - session.new - session.share - session.interrupt - session.compact - session.page.up - session.page.down - session.line.up - session.line.down - session.half.page.up - session.half.page.down - session.first - session.last - prompt.clear - prompt.submit - agent.cycle - type: string required: - command required: - type - properties Event.tui.toast.show: type: object properties: type: type: string const: tui.toast.show properties: type: object properties: title: type: string message: type: string variant: type: string enum: - info - success - warning - error duration: description: Duration in milliseconds default: 5000 type: number sessionID: description: Session ID associated with the notification type: string pattern: ^ses.* required: - message - variant required: - type - properties Event.tui.session.select: type: object properties: type: type: string const: tui.session.select properties: type: object properties: sessionID: description: Session ID to navigate to type: string pattern: ^ses.* required: - sessionID required: - type - properties Event.control.request: type: object properties: type: type: string const: control.request properties: $ref: '#/components/schemas/ControlRequest' required: - type - properties Event.control.cancelled: type: object properties: type: type: string const: control.cancelled properties: type: object properties: id: $ref: '#/components/schemas/ControlRequestID' sessionID: type: string pattern: ^ses.* reason: $ref: '#/components/schemas/ControlCancelReason' required: - id - sessionID - reason required: - type - properties Event.mcp.tools.changed: type: object properties: type: type: string const: mcp.tools.changed properties: type: object properties: server: type: string required: - server required: - type - properties Event.mcp.browser.open.failed: type: object properties: type: type: string const: mcp.browser.open.failed properties: type: object properties: mcpName: type: string url: type: string required: - mcpName - url required: - type - properties Event.permission.asked: type: object properties: type: type: string const: permission.asked properties: $ref: '#/components/schemas/PermissionRequest' required: - type - properties Event.permission.replied: type: object properties: type: type: string const: permission.replied properties: type: object properties: sessionID: type: string pattern: ^ses.* requestID: type: string pattern: ^per.* reply: type: string enum: - once - always - reject required: - sessionID - requestID - reply required: - type - properties Event.session.diff: type: object properties: type: type: string const: session.diff properties: type: object properties: sessionID: type: string pattern: ^ses.* diff: type: array items: $ref: '#/components/schemas/SnapshotFileDiff' required: - sessionID - diff required: - type - properties Event.session.error: type: object properties: type: type: string const: session.error properties: type: object properties: sessionID: type: string pattern: ^ses.* error: anyOf: - $ref: '#/components/schemas/ProviderAuthError' - $ref: '#/components/schemas/UnknownError' - $ref: '#/components/schemas/MessageOutputLengthError' - $ref: '#/components/schemas/MessageAbortedError' - $ref: '#/components/schemas/StructuredOutputError' - $ref: '#/components/schemas/ContextOverflowError' - $ref: '#/components/schemas/APIError' required: - type - properties Event.session.result: type: object properties: type: type: string const: session.result properties: type: object properties: sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* parentMessageID: type: string pattern: ^msg.* subtype: type: string enum: - success - error_aborted - error_during_execution - error_max_turns - error_max_budget - error_max_structured_output_retries stopReason: type: string finalText: type: string numTurns: type: integer minimum: 0 maximum: 9007199254740991 totalCostUsd: type: number usage: type: object properties: total: type: number input: type: number output: type: number reasoning: type: number cache: type: object properties: read: type: number write: type: number required: - read - write required: - input - output - reasoning - cache modelUsage: type: object propertyNames: type: string additionalProperties: type: object properties: tokens: type: object properties: total: type: number input: type: number output: type: number reasoning: type: number cache: type: object properties: read: type: number write: type: number required: - read - write required: - input - output - reasoning - cache cost: type: number required: - tokens - cost error: type: object properties: name: type: string message: type: string required: - name - message structuredOutput: {} required: - sessionID - subtype required: - type - properties Event.subagent.started: type: object properties: type: type: string const: subagent.started properties: type: object properties: sessionID: type: string pattern: ^ses.* parentSessionID: type: string pattern: ^ses.* childSessionID: type: string pattern: ^ses.* agent: type: string messageID: type: string pattern: ^msg.* callID: type: string taskID: type: string pattern: ^ses.* spawnMode: type: string enum: - fresh - inherit required: - sessionID - parentSessionID - childSessionID - agent - messageID - taskID - spawnMode required: - type - properties Event.subagent.progress: type: object properties: type: type: string const: subagent.progress properties: type: object properties: sessionID: type: string pattern: ^ses.* parentSessionID: type: string pattern: ^ses.* childSessionID: type: string pattern: ^ses.* agent: type: string messageID: type: string pattern: ^msg.* callID: type: string taskID: type: string pattern: ^ses.* spawnMode: type: string enum: - fresh - inherit status: type: string title: type: string required: - sessionID - parentSessionID - childSessionID - agent - messageID - taskID - spawnMode - status required: - type - properties Event.subagent.stopped: type: object properties: type: type: string const: subagent.stopped properties: type: object properties: sessionID: type: string pattern: ^ses.* parentSessionID: type: string pattern: ^ses.* childSessionID: type: string pattern: ^ses.* agent: type: string messageID: type: string pattern: ^msg.* callID: type: string taskID: type: string pattern: ^ses.* spawnMode: type: string enum: - fresh - inherit status: type: string enum: - completed - error - cancelled result: type: string error: type: string required: - sessionID - parentSessionID - childSessionID - agent - messageID - taskID - spawnMode - status required: - type - properties Event.session.rate_limit_hit: type: object properties: type: type: string const: session.rate_limit_hit properties: type: object properties: sessionID: type: string pattern: ^ses.* activeSessionID: type: string pattern: ^ses.* provider: type: string model: type: string attempt: type: integer exclusiveMinimum: 0 maximum: 9007199254740991 retryAfterSeconds: type: number minimum: 0 message: type: string required: - sessionID - activeSessionID - provider required: - type - properties Event.task.started: type: object properties: type: type: string const: task.started properties: type: object properties: sessionID: type: string pattern: ^ses.* activeSessionID: type: string pattern: ^ses.* taskID: type: string messageID: type: string pattern: ^msg.* partID: type: string tool: type: string agent: type: string required: - sessionID - activeSessionID - taskID - messageID - partID - tool - agent required: - type - properties Event.task.progress: type: object properties: type: type: string const: task.progress properties: type: object properties: sessionID: type: string pattern: ^ses.* activeSessionID: type: string pattern: ^ses.* taskID: type: string messageID: type: string pattern: ^msg.* partID: type: string tool: type: string agent: type: string title: type: string elapsedMs: type: number minimum: 0 required: - sessionID - activeSessionID - taskID - messageID - partID - tool - agent - elapsedMs required: - type - properties Event.task.notification: type: object properties: type: type: string const: task.notification properties: type: object properties: sessionID: type: string pattern: ^ses.* activeSessionID: type: string pattern: ^ses.* taskID: type: string messageID: type: string pattern: ^msg.* partID: type: string tool: type: string agent: type: string kind: type: string enum: - still_running elapsedMs: type: number minimum: 0 message: type: string required: - sessionID - activeSessionID - taskID - messageID - partID - tool - agent - kind - elapsedMs required: - type - properties Event.task.stopped: type: object properties: type: type: string const: task.stopped properties: type: object properties: sessionID: type: string pattern: ^ses.* activeSessionID: type: string pattern: ^ses.* taskID: type: string messageID: type: string pattern: ^msg.* partID: type: string tool: type: string agent: type: string status: type: string enum: - completed - error - interrupted durationMs: type: number minimum: 0 title: type: string error: type: string required: - sessionID - activeSessionID - taskID - messageID - partID - tool - agent - status - durationMs required: - type - properties Event.session.status: type: object properties: type: type: string const: session.status properties: type: object properties: sessionID: type: string pattern: ^ses.* status: $ref: '#/components/schemas/SessionStatus' required: - sessionID - status required: - type - properties Event.session.idle: type: object properties: type: type: string const: session.idle properties: type: object properties: sessionID: type: string pattern: ^ses.* required: - sessionID required: - type - properties Event.session.checkpoint.created: type: object properties: type: type: string const: session.checkpoint.created properties: type: object properties: sessionID: type: string pattern: ^ses.* checkpoint: $ref: '#/components/schemas/SessionCheckpoint' required: - sessionID - checkpoint required: - type - properties Event.session.rewound: type: object properties: type: type: string const: session.rewound properties: type: object properties: sessionID: type: string pattern: ^ses.* checkpointID: type: string pattern: ^chk.* affectedFiles: type: array items: type: string required: - sessionID - checkpointID - affectedFiles required: - type - properties Event.question.asked: type: object properties: type: type: string const: question.asked properties: $ref: '#/components/schemas/QuestionRequest' required: - type - properties Event.question.replied: type: object properties: type: type: string const: question.replied properties: $ref: '#/components/schemas/QuestionReplied' required: - type - properties Event.question.rejected: type: object properties: type: type: string const: question.rejected properties: $ref: '#/components/schemas/QuestionRejected' required: - type - properties Event.session.compacted: type: object properties: type: type: string const: session.compacted properties: type: object properties: sessionID: type: string pattern: ^ses.* required: - sessionID required: - type - properties Event.system.compact_boundary: type: object properties: type: type: string const: system.compact_boundary properties: type: object properties: sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* partID: type: string pattern: ^prt.* checkpointId: type: string auto: type: boolean overflow: type: boolean tailStartMessageID: type: string pattern: ^msg.* trigger: type: string enum: - auto - manual preCompactTokenCount: type: integer minimum: 0 maximum: 9007199254740991 compactionId: type: string pattern: ^msg.* preservedMessageIds: type: array items: type: string pattern: ^msg.* summaryText: type: string required: - sessionID - messageID - auto - overflow required: - type - properties Event.todo.updated: type: object properties: type: type: string const: todo.updated properties: type: object properties: sessionID: type: string pattern: ^ses.* todos: type: array items: $ref: '#/components/schemas/Todo' required: - sessionID - todos required: - type - properties Event.command.executed: type: object properties: type: type: string const: command.executed properties: type: object properties: name: type: string sessionID: type: string pattern: ^ses.* arguments: type: string messageID: type: string pattern: ^msg.* required: - name - sessionID - arguments - messageID required: - type - properties Event.vcs.branch.updated: type: object properties: type: type: string const: vcs.branch.updated properties: type: object properties: branch: type: string required: - type - properties Event.worktree.ready: type: object properties: type: type: string const: worktree.ready properties: type: object properties: name: type: string branch: type: string required: - name - branch required: - type - properties Event.worktree.failed: type: object properties: type: type: string const: worktree.failed properties: type: object properties: message: type: string required: - message required: - type - properties Event.pty.created: type: object properties: type: type: string const: pty.created properties: type: object properties: info: $ref: '#/components/schemas/Pty' required: - info required: - type - properties Event.pty.updated: type: object properties: type: type: string const: pty.updated properties: type: object properties: info: $ref: '#/components/schemas/Pty' required: - info required: - type - properties Event.pty.exited: type: object properties: type: type: string const: pty.exited properties: type: object properties: id: type: string pattern: ^pty.* exitCode: type: number required: - id - exitCode required: - type - properties Event.pty.deleted: type: object properties: type: type: string const: pty.deleted properties: type: object properties: id: type: string pattern: ^pty.* required: - id required: - type - properties Event.workspace.ready: type: object properties: type: type: string const: workspace.ready properties: type: object properties: name: type: string required: - name required: - type - properties Event.workspace.failed: type: object properties: type: type: string const: workspace.failed properties: type: object properties: message: type: string required: - message required: - type - properties Event.workspace.restore: type: object properties: type: type: string const: workspace.restore properties: type: object properties: workspaceID: type: string pattern: ^wrk.* sessionID: type: string pattern: ^ses.* total: type: integer minimum: 0 maximum: 9007199254740991 step: type: integer minimum: 0 maximum: 9007199254740991 required: - workspaceID - sessionID - total - step required: - type - properties Event.workspace.status: type: object properties: type: type: string const: workspace.status properties: type: object properties: workspaceID: type: string pattern: ^wrk.* status: type: string enum: - connected - connecting - disconnected - error required: - workspaceID - status required: - type - properties Event.message.updated: type: object properties: type: type: string const: message.updated properties: type: object properties: sessionID: type: string pattern: ^ses.* info: $ref: '#/components/schemas/Message' required: - sessionID - info required: - type - properties Event.message.removed: type: object properties: type: type: string const: message.removed properties: type: object properties: sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* required: - sessionID - messageID required: - type - properties Event.message.part.updated: type: object properties: type: type: string const: message.part.updated properties: type: object properties: sessionID: type: string pattern: ^ses.* part: $ref: '#/components/schemas/Part' time: type: number required: - sessionID - part - time required: - type - properties Event.message.part.removed: type: object properties: type: type: string const: message.part.removed properties: type: object properties: sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* partID: type: string pattern: ^prt.* required: - sessionID - messageID - partID required: - type - properties Event.session.created: type: object properties: type: type: string const: session.created properties: type: object properties: sessionID: type: string pattern: ^ses.* info: $ref: '#/components/schemas/Session' required: - sessionID - info required: - type - properties Event.session.updated: type: object properties: type: type: string const: session.updated properties: type: object properties: sessionID: type: string pattern: ^ses.* info: $ref: '#/components/schemas/Session' required: - sessionID - info required: - type - properties Event.session.deleted: type: object properties: type: type: string const: session.deleted properties: type: object properties: sessionID: type: string pattern: ^ses.* info: $ref: '#/components/schemas/Session' required: - sessionID - info required: - type - properties Project: type: object properties: id: type: string worktree: type: string vcs: type: string const: git name: type: string icon: type: object properties: url: type: string override: type: string color: type: string commands: type: object properties: start: description: Startup script to run when creating a new workspace (worktree) type: string time: type: object properties: created: type: number updated: type: number initialized: type: number required: - created - updated sandboxes: type: array items: type: string required: - id - worktree - time - sandboxes ControlRequest: type: object properties: id: $ref: '#/components/schemas/ControlRequestID' sessionID: type: string pattern: ^ses.* subtype: $ref: '#/components/schemas/ControlSubtype' payload: $ref: '#/components/schemas/ControlPayload' createdAt: type: number timeoutMs: type: number required: - id - sessionID - subtype - payload - createdAt - timeoutMs ControlRequestID: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ ControlCancelReason: type: string enum: - timeout - cancelled - shutdown PermissionRequest: type: object properties: id: type: string pattern: ^per.* sessionID: type: string pattern: ^ses.* permission: type: string patterns: type: array items: type: string metadata: type: object propertyNames: type: string additionalProperties: {} always: type: array items: type: string tool: type: object properties: messageID: type: string pattern: ^msg.* callID: type: string required: - messageID - callID required: - id - sessionID - permission - patterns - metadata - always SnapshotFileDiff: type: object properties: file: type: string patch: type: string additions: type: number deletions: type: number status: type: string enum: - added - deleted - modified required: - file - patch - additions - deletions ProviderAuthError: type: object properties: name: type: string const: ProviderAuthError data: type: object properties: providerID: type: string message: type: string required: - providerID - message required: - name - data UnknownError: type: object properties: name: type: string const: UnknownError data: type: object properties: message: type: string required: - message required: - name - data MessageOutputLengthError: type: object properties: name: type: string const: MessageOutputLengthError data: type: object properties: {} required: - name - data MessageAbortedError: type: object properties: name: type: string const: MessageAbortedError data: type: object properties: message: type: string required: - message required: - name - data StructuredOutputError: type: object properties: name: type: string const: StructuredOutputError data: type: object properties: message: type: string retries: type: number required: - message - retries required: - name - data ContextOverflowError: type: object properties: name: type: string const: ContextOverflowError data: type: object properties: message: type: string responseBody: type: string required: - message required: - name - data APIError: type: object properties: name: type: string const: APIError data: type: object properties: message: type: string statusCode: type: number isRetryable: type: boolean responseHeaders: type: object propertyNames: type: string additionalProperties: type: string responseBody: type: string metadata: type: object propertyNames: type: string additionalProperties: type: string required: - message - isRetryable required: - name - data SessionStatus: anyOf: - type: object properties: type: type: string const: idle required: - type - type: object properties: type: type: string const: retry attempt: type: number message: type: string next: type: number required: - type - attempt - message - next - type: object properties: type: type: string const: busy required: - type SessionCheckpoint: type: object properties: id: type: string pattern: ^chk.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* label: type: string source: type: string enum: - manual - auto metadata: type: object propertyNames: type: string additionalProperties: {} time: type: object properties: created: type: number updated: type: number required: - created - updated required: - id - sessionID - source - time QuestionRequest: type: object properties: id: type: string pattern: ^que.* sessionID: type: string pattern: ^ses.* questions: description: Questions to ask type: array items: $ref: '#/components/schemas/QuestionInfo' tool: $ref: '#/components/schemas/QuestionTool' required: - id - sessionID - questions QuestionReplied: type: object properties: sessionID: type: string pattern: ^ses.* requestID: type: string pattern: ^que.* answers: type: array items: $ref: '#/components/schemas/QuestionAnswer' required: - sessionID - requestID - answers QuestionRejected: type: object properties: sessionID: type: string pattern: ^ses.* requestID: type: string pattern: ^que.* required: - sessionID - requestID Todo: type: object properties: content: description: Brief description of the task type: string status: description: Current status of the task type: string enum: - pending - in_progress - completed - cancelled priority: description: Priority level of the task type: string enum: - high - medium - low required: - content - status - priority Pty: type: object properties: id: type: string pattern: ^pty.* title: type: string command: type: string args: type: array items: type: string cwd: type: string status: type: string enum: - running - exited pid: type: number required: - id - title - command - args - cwd - status - pid Message: anyOf: - $ref: '#/components/schemas/UserMessage' - $ref: '#/components/schemas/AssistantMessage' Part: anyOf: - $ref: '#/components/schemas/TextPart' - $ref: '#/components/schemas/SubtaskPart' - $ref: '#/components/schemas/ReasoningPart' - $ref: '#/components/schemas/FilePart' - $ref: '#/components/schemas/ToolPart' - $ref: '#/components/schemas/StepStartPart' - $ref: '#/components/schemas/StepFinishPart' - $ref: '#/components/schemas/SnapshotPart' - $ref: '#/components/schemas/PatchPart' - $ref: '#/components/schemas/AgentPart' - $ref: '#/components/schemas/RetryPart' - $ref: '#/components/schemas/CompactionPart' Session: type: object properties: id: type: string pattern: ^ses.* slug: type: string projectID: type: string workspaceID: type: string pattern: ^wrk.* directory: type: string parentID: type: string pattern: ^ses.* forkedFrom: type: string pattern: ^ses.* summary: type: object properties: additions: type: number deletions: type: number files: type: number diffs: type: array items: $ref: '#/components/schemas/SnapshotFileDiff' required: - additions - deletions - files share: type: object properties: url: type: string required: - url title: type: string tags: default: [] type: array items: type: string version: type: string time: type: object properties: created: type: number updated: type: number compacting: type: number archived: type: number required: - created - updated permission: $ref: '#/components/schemas/PermissionRuleset' revert: type: object properties: messageID: type: string pattern: ^msg.* partID: type: string pattern: ^prt.* snapshot: type: string checkpointId: type: string diff: type: string required: - messageID required: - id - slug - projectID - directory - title - version - time ControlSubtype: type: string enum: - can_use_tool - hook_callback - elicitation - mcp_message ControlPayload: type: object propertyNames: type: string additionalProperties: {} QuestionInfo: type: object properties: question: description: Complete question type: string header: description: Very short label (max 30 chars) type: string options: description: Available choices type: array items: $ref: '#/components/schemas/QuestionOption' multiple: description: Allow selecting multiple choices type: boolean custom: description: 'Allow typing a custom answer (default: true)' type: boolean required: - question - header - options QuestionTool: type: object properties: messageID: type: string pattern: ^msg.* callID: type: string required: - messageID - callID QuestionAnswer: type: array items: type: string UserMessage: type: object properties: id: type: string pattern: ^msg.* sessionID: type: string pattern: ^ses.* role: type: string const: user time: type: object properties: created: type: number required: - created parentMessageID: type: string pattern: ^msg.* format: $ref: '#/components/schemas/OutputFormat' summary: type: object properties: title: type: string body: type: string diffs: type: array items: $ref: '#/components/schemas/SnapshotFileDiff' required: - diffs agent: type: string model: type: object properties: providerID: type: string modelID: type: string variant: type: string required: - providerID - modelID system: type: string tools: type: object propertyNames: type: string additionalProperties: type: boolean required: - id - sessionID - role - time - agent - model AssistantMessage: type: object properties: id: type: string pattern: ^msg.* sessionID: type: string pattern: ^ses.* role: type: string const: assistant time: type: object properties: created: type: number completed: type: number required: - created error: anyOf: - $ref: '#/components/schemas/ProviderAuthError' - $ref: '#/components/schemas/UnknownError' - $ref: '#/components/schemas/MessageOutputLengthError' - $ref: '#/components/schemas/MessageAbortedError' - $ref: '#/components/schemas/StructuredOutputError' - $ref: '#/components/schemas/ContextOverflowError' - $ref: '#/components/schemas/APIError' parentID: type: string pattern: ^msg.* parentMessageID: type: string pattern: ^msg.* modelID: type: string providerID: type: string mode: type: string agent: type: string path: type: object properties: cwd: type: string root: type: string required: - cwd - root summary: type: boolean cost: type: number tokens: type: object properties: total: type: number input: type: number output: type: number reasoning: type: number cache: type: object properties: read: type: number write: type: number required: - read - write required: - input - output - reasoning - cache structured: {} variant: type: string finish: type: string required: - id - sessionID - role - time - parentID - modelID - providerID - mode - agent - path - cost - tokens TextPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: text text: type: string synthetic: type: boolean ignored: type: boolean time: type: object properties: start: type: number end: type: number required: - start metadata: type: object propertyNames: type: string additionalProperties: {} required: - id - sessionID - messageID - type - text SubtaskPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: subtask prompt: type: string description: type: string agent: type: string model: type: object properties: providerID: type: string modelID: type: string required: - providerID - modelID spawnMode: type: string enum: - fresh - inherit command: type: string required: - id - sessionID - messageID - type - prompt - description - agent ReasoningPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: reasoning text: type: string metadata: type: object propertyNames: type: string additionalProperties: {} time: type: object properties: start: type: number end: type: number required: - start required: - id - sessionID - messageID - type - text - time FilePart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: file mime: type: string filename: type: string url: type: string source: $ref: '#/components/schemas/FilePartSource' required: - id - sessionID - messageID - type - mime - url ToolPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: tool callID: type: string tool: type: string state: $ref: '#/components/schemas/ToolState' metadata: type: object propertyNames: type: string additionalProperties: {} required: - id - sessionID - messageID - type - callID - tool - state StepStartPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: step-start snapshot: type: string required: - id - sessionID - messageID - type StepFinishPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: step-finish reason: type: string snapshot: type: string cost: type: number tokens: type: object properties: total: type: number input: type: number output: type: number reasoning: type: number cache: type: object properties: read: type: number write: type: number required: - read - write required: - input - output - reasoning - cache required: - id - sessionID - messageID - type - reason - cost - tokens SnapshotPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: snapshot snapshot: type: string required: - id - sessionID - messageID - type - snapshot PatchPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: patch hash: type: string files: type: array items: type: string required: - id - sessionID - messageID - type - hash - files AgentPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: agent name: type: string source: type: object properties: value: type: string start: type: integer minimum: -9007199254740991 maximum: 9007199254740991 end: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - value - start - end required: - id - sessionID - messageID - type - name RetryPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: retry attempt: type: number error: $ref: '#/components/schemas/APIError' time: type: object properties: created: type: number required: - created required: - id - sessionID - messageID - type - attempt - error - time CompactionPart: type: object properties: id: type: string pattern: ^prt.* sessionID: type: string pattern: ^ses.* messageID: type: string pattern: ^msg.* type: type: string const: compaction auto: type: boolean overflow: type: boolean tail_start_id: type: string pattern: ^msg.* customInstructions: type: string required: - id - sessionID - messageID - type - auto PermissionRuleset: type: array items: $ref: '#/components/schemas/PermissionRule' QuestionOption: type: object properties: label: description: Display text (1-5 words, concise) type: string description: description: Explanation of choice type: string required: - label - description OutputFormat: anyOf: - $ref: '#/components/schemas/OutputFormatText' - $ref: '#/components/schemas/OutputFormatJsonSchema' FilePartSource: anyOf: - $ref: '#/components/schemas/FileSource' - $ref: '#/components/schemas/SymbolSource' - $ref: '#/components/schemas/ResourceSource' ToolState: anyOf: - $ref: '#/components/schemas/ToolStatePending' - $ref: '#/components/schemas/ToolStateRunning' - $ref: '#/components/schemas/ToolStateCompleted' - $ref: '#/components/schemas/ToolStateError' PermissionRule: type: object properties: permission: type: string pattern: type: string action: $ref: '#/components/schemas/PermissionAction' required: - permission - pattern - action OutputFormatText: type: object properties: type: type: string const: text required: - type OutputFormatJsonSchema: type: object properties: type: type: string const: json_schema schema: $ref: '#/components/schemas/JSONSchema' retryCount: default: 2 type: integer minimum: 0 maximum: 9007199254740991 required: - type - schema FileSource: type: object properties: text: $ref: '#/components/schemas/FilePartSourceText' type: type: string const: file path: type: string required: - text - type - path SymbolSource: type: object properties: text: $ref: '#/components/schemas/FilePartSourceText' type: type: string const: symbol path: type: string range: $ref: '#/components/schemas/Range' name: type: string kind: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - text - type - path - range - name - kind ResourceSource: type: object properties: text: $ref: '#/components/schemas/FilePartSourceText' type: type: string const: resource clientName: type: string uri: type: string required: - text - type - clientName - uri ToolStatePending: type: object properties: status: type: string const: pending input: type: object propertyNames: type: string additionalProperties: {} raw: type: string required: - status - input - raw ToolStateRunning: type: object properties: status: type: string const: running input: type: object propertyNames: type: string additionalProperties: {} title: type: string metadata: type: object propertyNames: type: string additionalProperties: {} time: type: object properties: start: type: number required: - start required: - status - input - time ToolStateCompleted: type: object properties: status: type: string const: completed input: type: object propertyNames: type: string additionalProperties: {} output: type: string title: type: string metadata: type: object propertyNames: type: string additionalProperties: {} time: type: object properties: start: type: number end: type: number compacted: type: number required: - start - end attachments: type: array items: $ref: '#/components/schemas/FilePart' required: - status - input - output - title - metadata - time ToolStateError: type: object properties: status: type: string const: error input: type: object propertyNames: type: string additionalProperties: {} error: type: string metadata: type: object propertyNames: type: string additionalProperties: {} time: type: object properties: start: type: number end: type: number required: - start - end required: - status - input - error - time PermissionAction: type: string enum: - allow - deny - ask JSONSchema: type: object propertyNames: type: string additionalProperties: {} FilePartSourceText: type: object properties: value: type: string start: type: integer minimum: -9007199254740991 maximum: 9007199254740991 end: type: integer minimum: -9007199254740991 maximum: 9007199254740991 required: - value - start - end Range: type: object properties: start: type: object properties: line: type: number character: type: number required: - line - character end: type: object properties: line: type: number character: type: number required: - line - character required: - start - end ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.