OpenAPI 3.1.0
HTTP API
Experimental HttpApi surface for selected instance routes.
Resource
server
get/api/statusGet server status
Return the server identity, connection URLs, and readiness status.
Operation IDserver.status
Responses
200ServerStatusapplication/jsonServerStatus400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
location
get/api/locationGet location
Resolve the requested location or the server default location.
Operation IDlocation.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Location.PublicInfoapplication/jsonLocation.PublicInfo400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
agent
get/api/agentList agents
Retrieve currently registered agents.
Operation IDagent.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataAgent.Info[]requiredItemsAgent.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/agent/{agentID}Get agent
Retrieve a single currently registered agent.
Operation IDagent.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
agentIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataAgent.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404AgentNotFoundErrorapplication/jsonAgentNotFoundErrorEncodedResource
plugin
Experimental plugin routes.
get/api/pluginList plugins
Retrieve enabled server plugins and their current status.
Operation IDplugin.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataPlugin.Info[]requiredItemsPlugin.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/plugin/checkCheck plugin updates
Check one or all package plugins for available updates.
Operation IDplugin.check
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjecttargetstring | nullstringor
nullResponses
200Successapplication/jsonobjectlocationLocation.PublicRefdataPlugin.Info[]requiredItemsPlugin.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/plugin/updateUpdate plugins
Update package plugins concurrently and notify active locations to reload them. Responds once every update has finished; fails when any update fails.
Operation IDplugin.update
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjecttargetsstring[]requiredItems
stringResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedResource
session
Experimental session routes.
get/api/sessionList sessions
Retrieve sessions in the requested order. Items keep that order across pages; use cursor.next or cursor.previous to move through the ordered list.
Operation IDsession.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
limit | query | string | nullMaximum number of sessions to return. Defaults to the newest 50 sessions. stringor null | No description |
order | query | "asc" | "desc" | nullSession order for the first page. Use desc for newest first or asc for oldest first. "asc" | "desc"Values "asc" | "desc"or null | No description |
search | query | string | nullstringor null | No description |
parentID | query | string | "null" | nullstring | "null"Filter by parent session. Use null to return only root sessions. stringpattern ^ses or "null"Values "null"or null | No description |
directory | query | string | nullstringor null | No description |
project | query | string | nullstringor null | No description |
subpath | query | string | nullstringor null | No description |
cursor | query | string | nullstringOpaque pagination cursor returned as cursor.previous or cursor.next in the previous response. or null | No description |
Responses
200SessionsResponseapplication/jsonSessionsResponse400InvalidCursorError | InvalidRequestErrorapplication/jsonInvalidCursorErrorEncoded | InvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/sessionCreate session
Create a session at the requested location.
Operation IDsession.create
Request body required
application/jsonobjectidstring | nullstringpattern ^ses
or
nulltitlestring | nullstringor
nullagentstring | nullstringor
nullmodelModel.Ref | nullor
nulllocationLocation.PublicRef | nullor
nullmetadataSession.Metadata | nullor
nullpermissionsPermission.Ruleset | nullor
nullResponses
200Successapplication/jsonobjectdataSession.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/experimental/session/statsGet session statistics
Aggregate local session activity, usage, and tool reliability for a time range.
Operation IDexperimental.session.stats
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
from | query | string | nullstringor null | No description |
to | query | string | nullstringor null | No description |
project | query | string | nullstringor null | No description |
timezone | query | string | nullstringor null | No description |
tools | query | "none" | "summary" | "detail" | null"none" | "summary" | "detail"Values "none" | "summary" | "detail"or null | No description |
Responses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/session/importImport session
Import a projected session transcript at the requested location. If parentID is supplied, the parent session must already exist; import parents before children.
Operation IDsession.import
Request body required
application/jsonobjectinfoSession.InfomessagesSession.Message.Info[]requiredItemsSession.Message.Info
locationLocation.PublicRef | nullor
nullResponses
200Successapplication/jsonobjectdataSession.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded409ConflictErrorapplication/jsonConflictErrorEncodedget/api/session/{sessionID}/exportExport session
Export a complete projected session transcript.
Operation IDsession.export
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
sanitize | query | "true" | "false" | null"true" | "false"Values "true" | "false"or null | No description |
Responses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded500UnknownErrorapplication/jsonUnknownErrorEncodedget/api/session/activeList active sessions
Retrieve foreground Session drains currently owned by this OpenCode process. Sessions absent from the result are inactive.
Operation IDsession.active
Responses
200Successapplication/jsonobjectdataobjectrequired400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/session/{sessionID}Get session
Retrieve a session by ID.
Operation IDsession.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
200Successapplication/jsonobjectdataSession.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncodeddelete/api/session/{sessionID}Delete session
Delete a session and its child sessions.
Operation IDsession.remove
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncodedpost/api/session/{sessionID}/forkFork session
Create a child session by copying projected history before a message. Omit before to copy the full history.
Operation IDsession.fork
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectbeforestring | nullstringpattern ^msg_
or
nullResponses
200Successapplication/jsonobjectdataSession.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundError | MessageNotFoundErrorapplication/jsonMessageNotFoundErrorEncoded | SessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedpost/api/session/{sessionID}/agentSwitch session agent
Switch the agent used by subsequent provider turns.
Operation IDsession.switchAgent
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectagentstringrequiredResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedpost/api/session/{sessionID}/modelSwitch session model
Switch the model used by subsequent provider turns.
Operation IDsession.switchModel
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectmodelModel.RefResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedpost/api/session/{sessionID}/renameRename session
Update the session title.
Operation IDsession.rename
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjecttitlestringrequiredResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedpost/api/session/{sessionID}/moveMove session
Move a session to another project directory, optionally transferring local changes.
Operation IDsession.move
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectdirectorystringrequireddeliverySession.Inbox.Delivery | nullor
nullResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncodedpost/api/session/{sessionID}/promptSend message
Durably admit one session input and schedule agent-loop execution unless resume is false.
Operation IDsession.prompt
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectidstring | nullstringpattern ^msg_
or
nulltextstringrequiredfilesPromptInput.FileAttachment[]agentsPrompt.AgentAttachment[]skillsPromptInput.SkillAttachment[]metadataobjectdeliverySession.Inbox.Delivery | nullor
nullresumeboolean | nullbooleanor
nullResponses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded409ConflictErrorapplication/jsonConflictErrorEncodedpost/api/session/{sessionID}/commandRun command
Execute a slash command callback immediately.
Operation IDsession.command
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectcommandstringrequiredtextstringrequiredfilesPromptInput.FileAttachment[]agentsPrompt.AgentAttachment[]skillsPromptInput.SkillAttachment[]deliverySession.Inbox.Delivery | nullor
nullResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundError | CommandNotFoundErrorapplication/jsonCommandNotFoundErrorEncoded | SessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded500CommandExecutionErrorapplication/jsonCommandExecutionErrorEncodedpost/api/session/{sessionID}/skillActivate skill
Activate a skill for a session by appending a skill message and resuming execution.
Operation IDsession.skill
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectidstring | nullstringpattern ^msg_
or
nullskillstringrequiredresumeboolean | nullbooleanor
nullResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundError | SkillNotFoundErrorapplication/jsonSkillNotFoundErrorEncoded | SessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedpost/api/session/{sessionID}/syntheticAdd synthetic message
Durably admit synthetic session input and schedule execution unless resume is false.
Operation IDsession.synthetic
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectidstring | nullstringpattern ^msg_
or
nulltextstringrequireddescriptionstring | nullstringor
nullmetadataobjectdeliverySession.Inbox.Delivery | nullor
nullresumeboolean | nullbooleanor
nullResponses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded409ConflictErrorapplication/jsonConflictErrorEncodedpost/api/session/{sessionID}/shellRun shell command
Execute one shell command in the session's working directory. Emits a shell.started event before execution and a shell.ended event with the merged output after.
Operation IDsession.shell
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectidstring | nullstringpattern ^evt_
or
nullcommandstringrequiredResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedpost/api/session/{sessionID}/compactCompact session
Durably admit a session compaction request. Steers by default: it runs at the next step boundary instead of waiting behind queued prompts.
Operation IDsession.compact
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectidstring | nullstringpattern ^msg_
or
nulldeliverySession.Inbox.Delivery | nullor
nullResponses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded409ConflictErrorapplication/jsonConflictErrorEncodedpost/api/session/{sessionID}/waitWait for session
Wait for a session agent loop to become idle.
Operation IDsession.wait
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedpost/api/session/{sessionID}/revert/stageStage session revert
Stage or move a reversible session boundary and optionally apply its file changes.
Operation IDsession.revert.stage
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectmessageIDstringrequiredpattern ^msg_
filesboolean | nullbooleanor
nullResponses
200Successapplication/jsonobjectdataSession.Revert400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404MessageNotFoundError | SessionNotFoundErrorapplication/jsonMessageNotFoundErrorEncoded | SessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded409SessionBusyErrorapplication/jsonSessionBusyErrorEncoded500UnknownErrorapplication/jsonUnknownErrorEncodedpost/api/session/{sessionID}/revert/clearClear staged revert
Operation IDsession.revert.clear
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded409SessionBusyErrorapplication/jsonSessionBusyErrorEncoded500UnknownErrorapplication/jsonUnknownErrorEncodedpost/api/session/{sessionID}/revert/commitCommit staged revert
Operation IDsession.revert.commit
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded409SessionBusyErrorapplication/jsonSessionBusyErrorEncodedget/api/session/{sessionID}/contextGet session context
Retrieve the active context messages for a session (all messages after the last compaction).
Operation IDsession.context
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
200Successapplication/jsonobjectdataSession.Message.Info[]requiredItemsSession.Message.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded500UnknownErrorapplication/jsonUnknownErrorEncodedget/api/session/{sessionID}/diffDiff session turns
Structured per-file diffs of the files a turn changed. A turn runs from the first prompt after the session was last idle until its next idle marker, so prompts steered in while it was busy belong to the same turn; `to` extends the range through a later turn. Compares the range's first recorded snapshot with its last; a step still running in the active session compares against the working copy. Ranges that span a location change are rejected. In sessions without any idle marker, a prompt's turn spans until the next user message.
Operation IDsession.diff
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
from | query | string | nullUser message whose turn to diff. Defaults to the turn of the newest user message. stringpattern ^msg_ or null | No description |
to | query | string | nullLater user message whose turn ends the range. Defaults to the turn of `from` alone. stringpattern ^msg_ or null | No description |
context | query | string | nullUnchanged lines around each hunk. Omit for full-file patches. stringor null | No description |
Responses
200Successapplication/jsonobjectdataFileDiff.Info[]requiredItemsFileDiff.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404MessageNotFoundError | SessionNotFoundErrorapplication/jsonMessageNotFoundErrorEncoded | SessionNotFoundErrorEncoded500UnknownErrorapplication/jsonUnknownErrorEncodedget/api/session/{sessionID}/inboxList session inbox
List durable enqueued session work not yet delivered, ordered by enqueue sequence. Includes user, synthetic, compaction, and move items.
Operation IDsession.inbox.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
200Successapplication/jsonobjectdataSession.Inbox.Info[]requiredItemsSession.Inbox.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncodeddelete/api/session/{sessionID}/inbox/{inboxID}Cancel inbox input
Cancel an inbox item that has not yet been delivered.
Operation IDsession.inbox.cancel
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
inboxIDrequired | path | stringpattern ^msg_ | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded409ConflictErrorapplication/jsonConflictErrorEncodedpost/api/session/{sessionID}/inbox/{inboxID}/steerSteer queued item
Change a queued inbox item to steer delivery and wake session execution.
Operation IDsession.inbox.steer
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
inboxIDrequired | path | stringpattern ^msg_ | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded409ConflictErrorapplication/jsonConflictErrorEncodedpost/api/session/{sessionID}/inbox/{inboxID}/queueQueue steered item
Change a steered inbox item to queued delivery.
Operation IDsession.inbox.queue
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
inboxIDrequired | path | stringpattern ^msg_ | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded409ConflictErrorapplication/jsonConflictErrorEncodedget/api/session/{sessionID}/instructions/entriesList instruction entries
List API-managed instruction entries attached to the session.
Operation IDsession.instructions.entry.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
200Successapplication/jsonobjectdataInstructionEntry.Info[]required400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedput/api/session/{sessionID}/instructions/entries/{key}Put instruction entry
Attach or replace one durable instruction entry. Changes announce as updates at the next step boundary.
Operation IDsession.instructions.entry.put
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
keyrequired | path | InstructionEntry.Key | No description |
Request body required
application/jsonobjectvalueobjectrequiredResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded413InstructionEntryValueTooLargeErrorapplication/jsonInstructionEntryValueTooLargeErrorEncodeddelete/api/session/{sessionID}/instructions/entries/{key}Remove instruction entry
Remove one instruction entry; the removal is announced to the model at the next step boundary.
Operation IDsession.instructions.entry.remove
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
keyrequired | path | InstructionEntry.Key | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedpost/api/session/{sessionID}/generateGenerate text from session context
Generate transient text from the current session context without mutating session history.
Operation IDsession.generate
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectpromptstringrequiredResponses
200SessionGenerateResponseapplication/jsonSessionGenerateResponse400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedget/api/experimental/session/{sessionID}/logRead the session log
Experimental durable session event log. Reads events after an exclusive aggregate sequence and continues with live events when follow=true.
Operation IDsession.log
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
after | query | string | nullstringor null | No description |
follow | query | "true" | "false" | null"true" | "false"Values "true" | "false"or null | No description |
Responses
200Successtext/event-streamobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncodedpost/api/session/{sessionID}/interruptInterrupt session execution
Interrupt active execution owned by this OpenCode process. Returns interrupted=true when an active execution was interrupted and false for the idle no-op. When continue=true, execution resumes pending steering input and next-in-line control items (manual compaction, moves) while queued prompts remain parked.
Operation IDsession.interrupt
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
continue | query | "true" | "false" | null"true" | "false"Values "true" | "false"or null | No description |
Responses
200SessionInterruptResponseapplication/jsonSessionInterruptResponse400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedpost/api/session/{sessionID}/backgroundBackground blocking session tools
Move active foreground backgroundable tools for this session into background observation. Idle requests are a no-op.
Operation IDsession.background
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedget/api/session/{sessionID}/message/{messageID}Get session message
Retrieve one projected message owned by the Session.
Operation IDsession.message
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
messageIDrequired | path | stringpattern ^msg_ | No description |
Responses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundError | MessageNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | MessageNotFoundErrorEncodedput/api/session/{sessionID}/environmentSet session environment
Replace the process environment used by local shell commands for this session.
Operation IDsession.environment
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectvariablesobjectrequiredAdditional properties
stringResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncodedpost/api/session/{sessionID}/viewView session
Mark the idle transition observed by the viewer as viewed.
Operation IDsession.view
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectidleintegerrequiredmin 0
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncodedget/api/session/{sessionID}/messageGet session messages
Retrieve projected messages for a session, optionally filtered by type. Items keep the requested order across pages; use cursor.next or cursor.previous to move through the ordered timeline, passing the same type filter on each page.
Operation IDmessage.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
limit | query | string | nullMaximum number of messages to return. When omitted, the endpoint returns its default page size. stringor null | No description |
order | query | "asc" | "desc" | nullMessage order for the first page. Use desc for newest first or asc for oldest first. "asc" | "desc"Values "asc" | "desc"or null | No description |
cursor | query | string | nullstringOpaque pagination cursor returned as cursor.previous or cursor.next in the previous response. Do not combine with order. or null | No description |
type | query | "agent-switched" | "model-switched" | "location-switched" | "user" | "synthetic" | "system" | "skill" | "shell" | "assistant" | "compaction" | nullFilter by message type before pagination. When omitted, all message types are returned. Pass the same type when following cursors. "agent-switched" | "model-switched" | "location-switched" | "user" | "synthetic" | "system" | "skill" | "shell" | "assistant" | "compaction"Values "agent-switched" | "model-switched" | "location-switched" | "user" | "synthetic" | "system" | "skill" | "shell" | "assistant" | "compaction"or null | No description |
Responses
200SessionMessagesResponseapplication/jsonSessionMessagesResponse400InvalidCursorError | InvalidRequestErrorapplication/jsonInvalidCursorErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded500UnknownErrorapplication/jsonUnknownErrorEncodedResource
model
Experimental model routes.
get/api/modelList models
Retrieve the current snapshot of available models ordered by release date. The snapshot may precede initial plugin settlement.
Operation IDmodel.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataModel.Info[]requiredItemsModel.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedget/api/model/defaultGet default model
Retrieve the model used when a session has no explicit model selection.
Operation IDmodel.default
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataModel.Info | nullrequiredor
null400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedResource
generate
Experimental one-shot generation routes.
post/api/generateGenerate text
Run one stateless model generation using the server's base configuration and return the assistant text. Uses the base configuration's default model when none is specified.
Operation IDgenerate.text
Request body required
application/jsonobjectpromptstringrequiredmodelModel.Ref | nullor
nullResponses
200GenerateTextResponseapplication/jsonGenerateTextResponse400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedResource
provider
Experimental provider routes.
get/api/providerList providers
Retrieve active AI providers so clients can show provider availability and configuration.
Operation IDprovider.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataProvider.Info[]requiredItemsProvider.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedget/api/provider/{providerID}Get provider
Retrieve a single AI provider so clients can inspect its availability and endpoint settings.
Operation IDprovider.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
providerIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataProvider.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404ProviderNotFoundErrorapplication/jsonProviderNotFoundErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedResource
integration
Integration discovery and authentication routes.
get/api/integrationList integrations
Retrieve available integrations and their authentication methods.
Operation IDintegration.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataIntegration.Info[]requiredItemsIntegration.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/integration/{integrationID}Get integration
Retrieve one integration and its authentication methods.
Operation IDintegration.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
integrationIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataIntegration.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404IntegrationNotFoundErrorapplication/jsonIntegrationNotFoundErrorEncodedpost/api/experimental/integration/wellknownAdd wellknown integration
Discover and persist an experimental wellknown integration source.
Operation IDexperimental.integration.wellknown.add
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjecturlstringrequiredResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/integration/{integrationID}/connect/keyConnect with key
Run a key authentication method and store the resulting credential.
Operation IDintegration.connect.key
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
integrationIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjectResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404IntegrationNotFoundErrorapplication/jsonIntegrationNotFoundErrorEncodedpost/api/integration/{integrationID}/connect/oauthBegin OAuth connection
Start an OAuth attempt and return the authorization details.
Operation IDintegration.oauth.connect
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
integrationIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjectResponses
200Successapplication/jsonobjectlocationLocation.PublicRef400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/integration/{integrationID}/connect/oauth/{attemptID}Get OAuth attempt status
Poll the current status of an OAuth attempt.
Operation IDintegration.oauth.status
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
integrationIDrequired | path | string | No description |
attemptIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRef400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404IntegrationNotFoundError | IntegrationAttemptNotFoundErrorapplication/jsonIntegrationNotFoundErrorEncoded | IntegrationAttemptNotFoundErrorEncodeddelete/api/integration/{integrationID}/connect/oauth/{attemptID}Cancel OAuth connection
Cancel an OAuth attempt and release its resources.
Operation IDintegration.oauth.cancel
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
integrationIDrequired | path | string | No description |
attemptIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/integration/{integrationID}/connect/oauth/{attemptID}/completeComplete OAuth connection
Complete a code-based OAuth attempt and store the resulting credential.
Operation IDintegration.oauth.complete
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
integrationIDrequired | path | string | No description |
attemptIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjectcodestring | nullstringor
nullResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404IntegrationNotFoundError | IntegrationAttemptNotFoundErrorapplication/jsonIntegrationNotFoundErrorEncoded | IntegrationAttemptNotFoundErrorEncodedpost/api/integration/{integrationID}/connect/commandBegin command connection
Start a command authentication attempt.
Operation IDintegration.command.connect
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
integrationIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjectmethodIDstringrequiredlabelstring | nullstringor
nullResponses
200Successapplication/jsonobjectlocationLocation.PublicRef400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404IntegrationNotFoundError | IntegrationMethodNotFoundErrorapplication/jsonIntegrationNotFoundErrorEncoded | IntegrationMethodNotFoundErrorEncodedget/api/integration/{integrationID}/connect/command/{attemptID}Get command attempt status
Poll the current status and output of a command authentication attempt.
Operation IDintegration.command.status
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
integrationIDrequired | path | string | No description |
attemptIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404IntegrationNotFoundError | IntegrationAttemptNotFoundErrorapplication/jsonIntegrationNotFoundErrorEncoded | IntegrationAttemptNotFoundErrorEncodeddelete/api/integration/{integrationID}/connect/command/{attemptID}Cancel command connection
Cancel a command authentication attempt and terminate its process.
Operation IDintegration.command.cancel
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
integrationIDrequired | path | string | No description |
attemptIDrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
mcp
MCP server and resource routes.
get/api/mcpList MCP servers
Retrieve configured MCP servers and their connection status.
Operation IDmcp.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataMcp.Server[]requiredItemsMcp.Server
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedput/api/experimental/mcp/{server}Add MCP server
Add an MCP server at runtime or replace an existing one, connecting it immediately.
Operation IDexperimental.mcp.add
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
serverrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjectconfigMcp.LocalConfigEncoded | Mcp.RemoteConfigEncodedrequiredResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodeddelete/api/experimental/mcp/{server}Remove MCP server
Stop an MCP server and remove it from the runtime set until restart.
Operation IDexperimental.mcp.remove
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
serverrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404McpServerNotFoundErrorapplication/jsonMcpServerNotFoundErrorEncodedpost/api/experimental/mcp/{server}/connectConnect MCP server
Connect an MCP server at runtime, overriding a disabled configuration until restart.
Operation IDexperimental.mcp.connect
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
serverrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404McpServerNotFoundErrorapplication/jsonMcpServerNotFoundErrorEncodedpost/api/experimental/mcp/{server}/disconnectDisconnect MCP server
Disconnect an MCP server at runtime, removing its tools until reconnected.
Operation IDexperimental.mcp.disconnect
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
serverrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404McpServerNotFoundErrorapplication/jsonMcpServerNotFoundErrorEncodedget/api/mcp/resourceList MCP resources
Retrieve resources and resource templates from connected MCP servers.
Operation IDmcp.resource.catalog
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRef400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
credential
patch/api/credential/{credentialID}Update credential
Update a stored credential label.
Operation IDcredential.update
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
credentialIDrequired | path | string | No description |
Request body required
application/jsonobjectlabelstringrequiredResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodeddelete/api/credential/{credentialID}Remove credential
Remove a stored integration credential.
Operation IDcredential.remove
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
credentialIDrequired | path | string | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/credential/{credentialID}/activateActivate credential
Activate a stored integration credential.
Operation IDcredential.activate
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
credentialIDrequired | path | string | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
project
Project routes.
get/api/projectList projects
List known projects.
Operation IDproject.list
Responses
200Successapplication/jsonProject[]ItemsProject
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpatch/api/project/{projectID}Update project
Update the project canonical directory, display metadata, and workspace commands.
Operation IDproject.update
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
projectIDrequired | path | string | No description |
Request body required
application/jsonobjectResponses
200Projectapplication/jsonProject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404ProjectNotFoundErrorapplication/jsonProjectNotFoundErrorEncodedResource
form
Session form routes.
get/api/form/requestList pending form requests
Retrieve pending forms for a location.
Operation IDform.request.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataForm.Info[]requiredItemsForm.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/session/{sessionID}/formList session forms
Retrieve pending forms for a session.
Operation IDsession.form.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | string | No description |
Responses
200Successapplication/jsonobjectdataForm.Info[]requiredItemsForm.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncodedpost/api/session/{sessionID}/formCreate session form
Create a form for a session.
Operation IDsession.form.create
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | string | No description |
Request body required
application/jsonForm.CreatePayloadResponses
200Successapplication/jsonobjectdataForm.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded409ConflictErrorapplication/jsonConflictErrorEncodedget/api/session/{sessionID}/form/{formID}Get session form
Retrieve a form for a session.
Operation IDsession.form.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | string | No description |
formIDrequired | path | stringpattern ^frm_ | No description |
Responses
200Successapplication/jsonobjectdataForm.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundError | FormNotFoundErrorapplication/jsonFormNotFoundErrorEncoded | SessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedget/api/session/{sessionID}/form/{formID}/stateGet form state
Retrieve the current state for a form.
Operation IDsession.form.state
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | string | No description |
formIDrequired | path | stringpattern ^frm_ | No description |
Responses
200Successapplication/jsonobjectdataForm.State400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundError | FormNotFoundErrorapplication/jsonFormNotFoundErrorEncoded | SessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedpost/api/session/{sessionID}/form/{formID}/replyReply to form
Submit an answer to a pending form.
Operation IDsession.form.reply
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | string | No description |
formIDrequired | path | stringpattern ^frm_ | No description |
Request body required
application/jsonForm.ReplyResponses
204<No Content>400FormInvalidAnswerError | InvalidRequestErrorapplication/jsonFormInvalidAnswerErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundError | FormNotFoundErrorapplication/jsonFormNotFoundErrorEncoded | SessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded409FormAlreadySettledErrorapplication/jsonFormAlreadySettledErrorEncodedpost/api/session/{sessionID}/form/{formID}/cancelCancel form
Cancel a pending form.
Operation IDsession.form.cancel
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | string | No description |
formIDrequired | path | stringpattern ^frm_ | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundError | FormNotFoundErrorapplication/jsonFormNotFoundErrorEncoded | SessionNotFoundErrorEncoded | SessionNotFoundErrorEncoded409FormAlreadySettledErrorapplication/jsonFormAlreadySettledErrorEncodedResource
permission
Experimental permission routes.
get/api/permission/requestList pending permission requests
Retrieve pending permission requests for a location.
Operation IDpermission.request.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataPermission.Request[]requiredItemsPermission.Request
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/permission/savedList saved permissions
Retrieve saved permissions, optionally filtered by project.
Operation IDpermission.saved.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
projectID | query | string | nullstringor null | No description |
Responses
200Successapplication/jsonobjectdataPermissionSaved.Info[]requiredItemsPermissionSaved.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodeddelete/api/permission/saved/{id}Remove saved permission
Remove a saved permission by ID.
Operation IDpermission.saved.remove
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
idrequired | path | string | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/session/{sessionID}/permissionList session permission requests
Retrieve pending permission requests owned by a session.
Operation IDsession.permission.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
200Successapplication/jsonobjectdataPermission.Request[]requiredItemsPermission.Request
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncodedpost/api/session/{sessionID}/permissionCreate permission request
Evaluate and, when approval is required, create a permission request for a session.
Operation IDsession.permission.create
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectidstring | nullstringpattern ^per
or
nullactionstringrequiredresourcesstring[]requiredItems
stringsavestring[]Items
stringmetadataobjectsourcePermission.Sourceagentstring | nullstringor
nullResponses
200Successapplication/jsonobjectdataobjectrequiredidstringrequiredpattern ^per
effectPermission.Effect400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedget/api/session/{sessionID}/permission/{requestID}Get permission request
Retrieve a pending permission request owned by a session.
Operation IDsession.permission.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
requestIDrequired | path | stringpattern ^per | No description |
Responses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundError | PermissionNotFoundErrorapplication/jsonPermissionNotFoundErrorEncoded | SessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedpost/api/session/{sessionID}/permission/{requestID}/replyReply to pending permission request
Respond to a pending permission request owned by a session.
Operation IDsession.permission.reply
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
requestIDrequired | path | stringpattern ^per | No description |
Request body required
application/jsonobjectreplyPermission.Replymessagestring | nullstringor
nullResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundError | PermissionNotFoundErrorapplication/jsonPermissionNotFoundErrorEncoded | SessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedput/api/session/{sessionID}/permission/rulesReplace session permission rules
Replace the session-scoped permission rules. Rules are evaluated after the agent's rules, and the last matching rule wins.
Operation IDsession.permission.rules
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonobjectpermissionsPermission.RulesetResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404SessionNotFoundErrorapplication/jsonSessionNotFoundErrorEncoded | SessionNotFoundErrorEncodedResource
filesystem
Experimental location-scoped filesystem routes.
get/api/fs/read/*Read file
Serve one file relative to the requested location.
Operation IDfs.read
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/octet-streamstring<binary>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404FileNotFoundErrorapplication/jsonFileNotFoundErrorEncodedget/api/fs/listList directory
List direct children using an absolute path or a path relative to the requested location, including parents and siblings outside its directory. Entry paths remain relative to the requested location; listing does not switch locations.
Operation IDfs.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
path | query | string | nullAn absolute path or a path relative to the requested location. Defaults to the location directory. stringor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataFileSystem.Entry[]requiredItemsFileSystem.Entry
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/fs/findFind files
Find recursively ranked filesystem entries relative to the requested location.
Operation IDfs.find
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
queryrequired | query | string | No description |
type | query | "file" | "directory"Values "file" | "directory" | No description |
limit | query | string | nullstringor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataFileSystem.Entry[]requiredItemsFileSystem.Entry
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
command
Experimental command routes.
get/api/commandList commands
Retrieve currently registered commands.
Operation IDcommand.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataCommand.Info[]requiredItemsCommand.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
skill
Experimental skill routes.
get/api/skillList skills
Retrieve currently registered skills.
Operation IDskill.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataSkill.Info[]requiredItemsSkill.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
rpc
Plugin RPC routes.
post/api/rpc/{rpcID}/{method}Call a plugin RPC
Dispatch a method to the currently registered RPC at the requested location.
Operation IDrpc.call
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
rpcIDrequired | path | string | No description |
methodrequired | path | string | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonRpc.InputResponses
200Rpc.Outputapplication/jsonRpc.Output400RpcError | InvalidRequestErrorapplication/jsonRpcErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded500RpcInternalErrorapplication/jsonRpcInternalErrorEncodedResource
event
Experimental event stream routes.
get/api/eventSubscribe to events
Subscribe to native events and plugin RPC events across all server locations. Volatile by contract: a slow consumer overflows and fails the stream, and events during disconnection are missed.
Operation IDevent.subscribe
Responses
200Successtext/event-streamobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
pty
Experimental location-scoped PTY routes.
get/api/ptyList PTY sessions
List PTY sessions for a location, including exited sessions retained until removal.
Operation IDpty.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataPty[]requiredItemsPty
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/ptyCreate PTY session
Create a pseudo-terminal session for a location.
Operation IDpty.create
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjectcommandstringargsstring[]Items
stringcwdstringtitlestringenvobjectAdditional properties
stringResponses
200Successapplication/jsonobjectlocationLocation.PublicRefdataPty400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/pty/{ptyID}Get PTY session
Get one PTY session, including its exit code once exited.
Operation IDpty.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataPty400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncodedput/api/pty/{ptyID}Update PTY session
Update the title or viewport size of one PTY session.
Operation IDpty.update
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjecttitlestringsizeobjectrowsintegerrequired> 0
colsintegerrequired> 0
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataPty400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncodeddelete/api/pty/{ptyID}Remove PTY session
Terminate and remove one PTY session.
Operation IDpty.remove
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncodedpost/api/pty/{ptyID}/connect-tokenCreate PTY WebSocket token
Create a short-lived single-use ticket for opening a PTY WebSocket connection.
Operation IDpty.connect.token
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
x-opencode-ticket | header | string | nullstringor null | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRef400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded403ForbiddenErrorapplication/jsonForbiddenErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncodedget/api/pty/{ptyID}/connectConnect to PTY session
Establish a WebSocket connection streaming PTY output and accepting terminal input.
Operation IDpty.connect
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
location[directory] | query | string | No description |
cursor | query | string | No description |
ticket | query | string | No description |
Responses
200Successapplication/jsonboolean400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded403ForbiddenErrorapplication/jsonForbiddenErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncodedResource
persistentPty
Prototype persistent PTY routes.
get/api/experimental/session/{sessionID}/terminal/readRead the session's most recently controlled terminal
Read the last physical rows without changing selection or taking control. Omitted lines uses the live terminal height; larger counts include retained history. Blank rows are preserved. Screen dimensions and cursor remain relative to the live screen. Returns null when no current terminal exists. Selection is server-local and resets on restart. Experimental: may change without compatibility guarantees.
Operation IDserver.experimental.persistentPty.read
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
lines | query | PersistentPty.ReadLinesEncoded | null | No description |
Responses
200Successapplication/jsonobjectdataPersistentPty.ReadResult | nullrequiredor
null400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedget/api/experimental/session/{sessionID}/terminal
Operation IDserver.experimental.persistentPty.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Responses
200Successapplication/jsonobjectdataPersistentPty.Info[]requiredItemsPersistentPty.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedpost/api/experimental/session/{sessionID}/terminal
Operation IDserver.experimental.persistentPty.create
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
sessionIDrequired | path | stringpattern ^ses | No description |
Request body required
application/jsonPersistentPty.CreateInputResponses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedpost/api/experimental/persistent-pty/shutdown
Operation IDserver.experimental.persistentPty.shutdown
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedpost/api/experimental/persistent-pty/handoff
Operation IDserver.experimental.persistentPty.handoff
Responses
200Successapplication/jsonobjecthandoffPersistentPty.Handoff | nullrequiredor
null400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedget/api/experimental/persistent-pty/{ptyID}
Operation IDserver.experimental.persistentPty.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
Responses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedput/api/experimental/persistent-pty/{ptyID}
Operation IDserver.experimental.persistentPty.update
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
Request body required
application/jsonPersistentPty.UpdateInputResponses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodeddelete/api/experimental/persistent-pty/{ptyID}
Operation IDserver.experimental.persistentPty.remove
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedget/api/experimental/persistent-pty/{ptyID}/snapshot
Operation IDserver.experimental.persistentPty.snapshot
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
Responses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedpost/api/experimental/persistent-pty/{ptyID}/connect-token
Operation IDserver.experimental.persistentPty.connectToken
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
x-opencode-ticket | header | string | nullstringor null | No description |
Responses
200Successapplication/jsonobject400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded403ForbiddenErrorapplication/jsonForbiddenErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedget/api/experimental/persistent-pty/{ptyID}/connectConnect to a persistent PTY
Stream persistent PTY output through the OpenCode server.
Operation IDpersistentPty.connect
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
ptyIDrequired | path | stringpattern ^pty | No description |
cursor | query | string | No description |
role | query | string | No description |
attachment_id | query | string | No description |
takeover | query | string | No description |
input_protocol | query | string | No description |
ticket | query | string | No description |
Responses
200Successapplication/jsonboolean400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded403ForbiddenErrorapplication/jsonForbiddenErrorEncoded404PtyNotFoundErrorapplication/jsonPtyNotFoundErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedResource
shell
Experimental location-scoped shell command routes.
get/api/shellList running shell commands
List currently running shell commands for a location. Exited commands are not included.
Operation IDshell.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataShell.Info[]requiredItemsShell.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/shellRun shell command
Spawn one non-interactive shell command for a location. Combined stdout/stderr is captured to a file pageable via output.
Operation IDshell.create
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjectcommandstringrequiredcwdstringtimeoutintegerrequiredmin 0
metadataobjectResponses
200Successapplication/jsonobjectlocationLocation.PublicRefdataShell.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/shell/{id}Get shell command
Get one shell command, including its status and exit code once exited.
Operation IDshell.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
idrequired | path | stringpattern ^sh_ | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataShell.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404ShellNotFoundErrorapplication/jsonShellNotFoundErrorEncodeddelete/api/shell/{id}Remove shell command
Terminate and remove one shell command and its retained output.
Operation IDshell.remove
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
idrequired | path | stringpattern ^sh_ | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404ShellNotFoundErrorapplication/jsonShellNotFoundErrorEncodedpatch/api/shell/{id}/timeoutUpdate shell timeout
Replace a running shell command's timeout from now, or clear it with zero.
Operation IDshell.timeout
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
idrequired | path | stringpattern ^sh_ | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjecttimeoutintegerrequiredmin 0
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataShell.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404ShellNotFoundErrorapplication/jsonShellNotFoundErrorEncodedget/api/shell/{id}/outputRead shell output
Page through captured combined output by absolute byte cursor.
Operation IDshell.output
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
idrequired | path | stringpattern ^sh_ | No description |
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
cursor | query | stringpattern ^[+-]?\d*\.?\d+(?:[Ee][+-]?\d+)?$ | No description |
limit | query | stringpattern ^[+-]?\d*\.?\d+(?:[Ee][+-]?\d+)?$ | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataobjectrequiredoutputstringrequiredcursorintegerrequiredmin 0
sizeintegerrequiredmin 0
truncatedbooleanrequired400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded404ShellNotFoundErrorapplication/jsonShellNotFoundErrorEncodedResource
reference
Location-scoped project references.
get/api/referenceList references
List references available in the requested location.
Operation IDreference.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataReference.Info[]requiredItemsReference.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
worktree
Location-scoped worktree management routes.
get/api/worktreeList worktrees
Discover worktrees through the requested location's strategies and return its project's inventory.
Operation IDworktree.list
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Worktree.Listapplication/jsonWorktree.List400WorktreeError | InvalidRequestErrorapplication/jsonWorktreeErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/worktreeCreate worktree
Create a local worktree using the location's registered strategy and directory defaults, then run the project's setup script.
Operation IDworktree.create
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonWorktree.CreateInputResponses
200Worktree.Infoapplication/jsonWorktree.Info400WorktreeError | InvalidRequestErrorapplication/jsonWorktreeErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodeddelete/api/worktreeRemove worktree
Remove a managed worktree from the requested location's project using its recorded strategy.
Operation IDworktree.remove
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonWorktree.RemoveInputResponses
204<No Content>400WorktreeError | InvalidRequestErrorapplication/jsonWorktreeErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpost/api/worktree/refreshRefresh worktrees
Discover worktrees from the requested location and reconcile the shared project inventory.
Operation IDworktree.refresh
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
204<No Content>400WorktreeError | InvalidRequestErrorapplication/jsonWorktreeErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
vcs
Location-scoped version control routes.
get/api/vcsVCS info
Get current and default branch information for the requested location.
Operation IDvcs.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataVcs.Info400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/vcs/baseVCS review base
Infer a local review base from named branch creation history, or the repository default only when currently on that branch. Returns null before the first commit or when the provider lacks base metadata; ambiguous Git history requires an explicit base on diff requests.
Operation IDvcs.base
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataVcs.Base | nullrequiredor
null400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedget/api/vcs/statusVCS status
List uncommitted working-copy changes relative to the requested location.
Operation IDvcs.status
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataVcs.FileStatus[]requiredItemsVcs.FileStatus
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/vcs/branchesVCS branches
List local and remote branches available at the requested location.
Operation IDvcs.branches
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
search | query | string | nullstringor null | No description |
limit | query | string | nullstringor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataVcs.BranchList400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/vcs/diffVCS diff
Diff HEAD to the working copy (working), the base merge-base to the working copy (branch), or the base merge-base to HEAD (committed). Omitting base preserves repository-default comparison; supplying it overrides the comparison without saving it.
Operation IDvcs.diff
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
moderequired | query | Vcs.Mode | No description |
base | query | string | No description |
context | query | string | nullstringor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataFileDiff.Info[]requiredItemsFileDiff.Info
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedResource
debug
get/api/debug/locationList loaded locations
List locations currently loaded by the server.
Operation IDdebug.location.list
Responses
200Successapplication/jsonLocation.PublicRef[]ItemsLocation.PublicRef
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodeddelete/api/debug/locationEvict a loaded location
Dispose the requested location's cached services so its next use boots them fresh.
Operation IDdebug.location.evict
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
migration
get/api/experimental/migration/v1Get V1 migration status
Return the progress of the V1 to V2 session history migration.
Operation IDexperimental.migration.v1.status
Responses
200Successapplication/jsonobject | object | objectobjectstatus"required" | "completed"requiredValues
"required" | "completed"or
objectstatus"running"requiredValues
"running"progressobjectrequiredlabelstringrequirednumeratorinteger | nullintegermin 0
or
nulldenominatorinteger | nullintegermin 0
or
nullor
objectstatus"error"requiredValues
"error"errorstringrequired400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedResource
websearch
Location-scoped web search routes.
get/api/websearch/providerList web search providers
Return the registered web search providers.
Operation IDwebsearch.providers
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonobjectlocationLocation.PublicRefdataWebSearch.Provider[]requiredItemsWebSearch.Provider
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedpost/api/websearchSearch the web
Run one web search through the selected provider. Specify a provider to override the configured default.
Operation IDwebsearch.query
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Request body required
application/jsonobjectquerystringrequiredproviderIDstringResponses
200Successapplication/jsonobjectlocationLocation.PublicRef400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded | InvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncoded503ServiceUnavailableErrorapplication/jsonServiceUnavailableErrorEncodedResource
config
Location-scoped configuration routes.
get/api/configGet configuration
Return configuration documents and discovery sources for the requested location, from lowest to highest priority.
Operation IDconfig.get
Parameters
| Name | Location | Type | Description |
|---|---|---|---|
location | query | object | nullobjectdirectorystring | nullstringor nullor null | No description |
Responses
200Successapplication/jsonConfig.Entry[]ItemsConfig.Entry
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedget/api/config/shellList available shells
Return shells available to terminal and agent execution.
Operation IDconfig.shells
Responses
200Successapplication/jsonConfigShell.Option[]ItemsConfigShell.Option
400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedpatch/api/experimental/configUpdate global configuration
Patch supported fields in the highest-precedence global configuration document.
Operation IDexperimental.config.update
Request body required
application/jsonConfig.PatchResponses
204<No Content>400InvalidRequestErrorapplication/jsonInvalidRequestErrorEncoded401UnauthorizedErrorapplication/jsonUnauthorizedErrorEncodedComponents
Schemas
Reusable data types referenced by API operations.
Agent.Colorstring
stringAgent.Infoobject
objectidstringrequirednamestringrequiredmodelModel.RefrequestProvider.Requestsystemstringdescriptionstringmode"subagent" | "primary" | "all"requiredValues
"subagent" | "primary" | "all"hiddenbooleanrequiredcolorAgent.Colorstepsinteger> 0
permissionsPermission.RulesetAgentNotFoundErrorEncodedobject
object_tag"AgentNotFoundError"requiredValues
"AgentNotFoundError"agentIDstringrequiredmessagestringrequiredCommand.Infoobject
objectnamestringrequireddescriptionstringCommandExecutionErrorEncodedobject
object_tag"CommandExecutionError"requiredValues
"CommandExecutionError"commandstringrequiredmessagestringrequiredCommandNotFoundErrorEncodedobject
object_tag"CommandNotFoundError"requiredValues
"CommandNotFoundError"commandstringrequiredmessagestringrequiredConfig.AgentEncodedobject
objectmodelstring | objectstringpattern ^[^/#]+\/[^#]+(?:#[^#]+)?$
or
objectproviderIDstringrequiredpattern ^[^/#]+$
modelstringrequiredpattern ^[^#]+$
variantstringpattern ^[^#]+$
requestobjectheadersobjectAdditional properties
stringbodyobjectsystemstringdescriptionstringmode"subagent" | "primary" | "all"Values
"subagent" | "primary" | "all"hiddenbooleancolorstringpattern ^#[0-9a-fA-F]{6}$
stepsinteger> 0
disabledbooleanpermissionsPermission.RulesetConfig.CommandEncodedobject
objecttemplatestringrequireddescriptionstringagentstringmodelstring | objectstringpattern ^[^/#]+\/[^#]+(?:#[^#]+)?$
or
objectproviderIDstringrequiredpattern ^[^/#]+$
modelstringrequiredpattern ^[^#]+$
variantstringpattern ^[^#]+$
subagentbooleansubtaskbooleanDeprecated alias for subagent.
Config.DirectoryEncodedobject
objecttype"directory"requiredValues
"directory"pathstringrequiredConfig.DocumentEncodedobject
objectConfig.EntryConfig.DocumentEncoded | Config.DirectoryEncoded
Config.DocumentEncoded | Config.DirectoryEncodedConfig.Formatter.EntryEncodedobject
objectdisabledbooleancommandstring[]Items
stringenvironmentobjectAdditional properties
stringextensionsstring[]Items
stringConfig.InfoEncodedobject
object$schemastringshellstringmodelstring | objectstringpattern ^[^/#]+\/[^#]+(?:#[^#]+)?$
or
objectproviderIDstringrequiredpattern ^[^/#]+$
modelstringrequiredpattern ^[^#]+$
variantstringpattern ^[^#]+$
default_agentstringupdate"disable" | "notify" | "auto"Values
"disable" | "notify" | "auto"share"manual" | "auto" | "disabled"Values
"manual" | "auto" | "disabled"enterpriseobjecturlstringusernamestringpermissionsPermission.RulesetagentsobjectAdditional propertiesConfig.AgentEncoded
snapshotsbooleanwatcherobjectignorestring[]Items
stringformatterboolean | objectbooleanor
objectAdditional propertiesConfig.Formatter.EntryEncoded
lspboolean | objectbooleanor
objectAdditional properties
object | Config.LSP.ServerEncodedobjectdisabledtruerequiredValues
truemediaobjectimageobjectauto_resizebooleanmax_widthinteger> 0
max_heightinteger> 0
max_base64_bytesinteger> 0
tool_outputobjectmax_linesinteger> 0
max_bytesinteger> 0
mcpobjecttimeoutobjectstartupinteger> 0
cataloginteger> 0
executioninteger> 0
serversobjectAdditional properties
Mcp.LocalConfigEncoded | Mcp.RemoteConfigEncodedcompactionobjectautobooleankeepobjecttokensintegermin 0
bufferintegermin 0
skillsstring[]Items
stringcommandsobjectAdditional propertiesConfig.CommandEncoded
instructionsstring[]Items
stringreferencesobjectAdditional properties
string | Config.Reference.GitEncoded | Config.Reference.LocalEncodedwebsearchfalse | ConfigWebSearch.InfoEncodedfalseValues
falsepluginsstring | Config.Plugin.EntryEncoded[]Items
string | Config.Plugin.EntryEncodedstringworktreeConfig.Worktreewarmingboolean | Config.WarmingEncodedbooleanprovidersobjectAdditional propertiesConfig.ProviderEncoded
experimentalobjectportable_shell_scannerbooleansubagent_depthintegermin 0
policiesobject[]Items
objectaction"provider.use"requiredValues
"provider.use"resourcestringrequiredeffect"allow" | "deny"requiredValues
"allow" | "deny"Config.LSP.ServerEncodedobject
objectcommandstring[]requiredItems
stringextensionsstring[]Items
stringdisabledbooleanenvobjectAdditional properties
stringinitializationobjectConfig.Model.CostEncodedobject
objecttierobjecttype"context"requiredValues
"context"sizeintegerrequiredcacheobjectConfig.ModelEncodedobject
objectcompactionProvider.CompactionwebsocketbooleanmodelIDstringfamilystringnamestringcompatibilityModel.CompatibilitypackagestringsettingsobjectheadersobjectAdditional properties
stringbodyobjectcapabilitiesModel.Capabilitiesvariantsobject[]Items
objectidstringrequiredsettingsobjectheadersobjectAdditional properties
stringbodyobjectcostConfig.Model.CostEncoded | Config.Model.CostEncoded[]or
Config.Model.CostEncoded[]disabledbooleanlimitobjectcontextintegerinputintegeroutputintegerConfig.Patchobject
objectshellstring | nullrequiredstringor
nullConfig.Plugin.EntryEncodedobject
objectpackagestringrequiredoptionsobjectConfig.ProviderEncodedobject
objectcompactionProvider.Compactionwebsocketbooleancanonicalstringnamestringenvstring[]Items
stringpackagestringsettingsobjectheadersobjectAdditional properties
stringbodyobjectmodelsobjectAdditional propertiesConfig.ModelEncoded
Config.Reference.GitEncodedobject
objectrepositorystringrequiredbranchstringdescriptionstringhiddenbooleanConfig.Reference.LocalEncodedobject
objectpathstringrequireddescriptionstringhiddenbooleanConfig.WarmingEncodedobject
objectpromptstringintervalstringdurationstringConfig.Worktreeobject
objectdirectorystringrequiredConfigShell.Optionobject
objectpathstringrequirednamestringrequiredacceptablebooleanrequiredConfigWebSearch.InfoEncodedobject
objectprovider"random" | stringrequired"random"Reuse a randomly selected provider until it is rate limited, then switch to another available provider.
Values
"random"or
stringConflictErrorEncodedobject
object_tag"ConflictError"requiredValues
"ConflictError"messagestringrequiredresourcestring | nullstringor
nullConnection.CredentialInfoobject
objecttype"credential"requiredValues
"credential"idstringrequiredlabelstringrequiredConnection.EnvInfoobject
objecttype"env"requiredValues
"env"namestringrequiredConnection.InfoConnection.CredentialInfo | Connection.EnvInfo
Connection.CredentialInfo | Connection.EnvInfoFileDiff.Infoobject
objectfilestringrequiredpatchstringrequiredadditionsintegerrequiredmin 0
deletionsintegerrequiredmin 0
status"added" | "deleted" | "modified"requiredValues
"added" | "deleted" | "modified"FileNotFoundErrorEncodedobject
object_tag"FileNotFoundError"requiredValues
"FileNotFoundError"pathstringrequiredmessagestringrequiredFileSystem.Entryobject
objectpathstringrequiredtype"file" | "directory"requiredValues
"file" | "directory"ForbiddenErrorEncodedobject
object_tag"ForbiddenError"requiredValues
"ForbiddenError"messagestringrequiredForm.Answerobject
objectAdditional propertiesForm.Value
Form.BooleanFieldobject
objectkeystringrequiredtitlestringdescriptionstringrequiredbooleanwhenForm.When[]ItemsForm.When
type"boolean"requiredValues
"boolean"defaultbooleanForm.CreatePayloadobject
objectForm.ExternalFieldobject
objectkeystringrequiredtype"external"requiredValues
"external"urlstringrequiredtitlestringdescriptionstringForm.FieldForm.StringField | Form.NumberField | Form.IntegerField | Form.BooleanField | Form.MultiselectField | Form.ExternalField
Form.StringField | Form.NumberField | Form.IntegerField | Form.BooleanField | Form.MultiselectField | Form.ExternalFieldForm.FieldsForm.Field[]
Form.Fields_1Form.Field[]
Form.Fields_2Form.Field[]
Form.Infoobject
objectidstringrequiredpattern ^frm_
sessionIDstringrequiredtitlestringrequiredmetadataForm.MetadatafieldsForm.Fields_2Form.IntegerFieldobject
objectkeystringrequiredtitlestringdescriptionstringrequiredbooleanwhenForm.When[]ItemsForm.When
type"integer"requiredValues
"integer"minimumnumber | "Infinity" | "-Infinity" | "NaN"numberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"maximumnumber | "Infinity" | "-Infinity" | "NaN"numberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"defaultnumber | "Infinity" | "-Infinity" | "NaN"numberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"Form.Metadataobject
objectForm.MultiselectFieldobject
objectkeystringrequiredtitlestringdescriptionstringrequiredbooleanwhenForm.When[]ItemsForm.When
type"multiselect"requiredValues
"multiselect"optionsForm.Option[]requiredItemsForm.Option
minItemsintegermin 0
maxItemsintegermin 0
custombooleandefaultstring[]Items
stringForm.NumberFieldobject
objectkeystringrequiredtitlestringdescriptionstringrequiredbooleanwhenForm.When[]ItemsForm.When
type"number"requiredValues
"number"minimumnumber | "Infinity" | "-Infinity" | "NaN"numberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"maximumnumber | "Infinity" | "-Infinity" | "NaN"numberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"defaultnumber | "Infinity" | "-Infinity" | "NaN"numberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"Form.Optionobject
objectvaluestringrequiredlabelstringrequireddescriptionstringForm.Replyobject
objectanswerForm.AnswerForm.Stateobject | object | object
object | object | objectobjectstatus"pending"requiredValues
"pending"or
objectstatus"answered"requiredValues
"answered"answerForm.Answeror
objectstatus"cancelled"requiredValues
"cancelled"Form.StringFieldobject
objectkeystringrequiredtitlestringdescriptionstringrequiredbooleanwhenForm.When[]ItemsForm.When
type"string"requiredValues
"string"format"email" | "uri" | "date" | "date-time"Values
"email" | "uri" | "date" | "date-time"minLengthintegermin 0
maxLengthintegermin 0
patternstringplaceholderstringdefaultstringoptionsForm.Option[]ItemsForm.Option
custombooleanForm.Valuestring | number | "Infinity" | "-Infinity" | "NaN" | boolean | string[]
string | number | "Infinity" | "-Infinity" | "NaN" | boolean | string[]stringor
number | "Infinity" | "-Infinity" | "NaN"numberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"or
booleanor
string[]Items
stringForm.Whenobject
objectkeystringrequiredop"eq" | "neq"requiredValues
"eq" | "neq"valuestring | number | "Infinity" | "-Infinity" | "NaN" | booleanrequiredstringor
number | "Infinity" | "-Infinity" | "NaN"numberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"or
booleanFormAlreadySettledErrorEncodedobject
object_tag"FormAlreadySettledError"requiredValues
"FormAlreadySettledError"idstringrequiredmessagestringrequiredFormInvalidAnswerErrorEncodedobject
object_tag"FormInvalidAnswerError"requiredValues
"FormInvalidAnswerError"idstringrequiredmessagestringrequiredFormNotFoundErrorEncodedobject
object_tag"FormNotFoundError"requiredValues
"FormNotFoundError"idstringrequiredmessagestringrequiredGenerateTextResponseobject
objectdataobjectrequiredtextstringrequiredInstructionEntry.Infoobject
objectvalueobjectrequiredJSON value attached to the session's instructions
InstructionEntry.Keystring
stringInstruction entry key (lowercase alphanumerics plus . _ -)
pattern ^[a-z0-9][a-z0-9._-]*$
InstructionEntryValueTooLargeErrorEncodedobject
object_tag"InstructionEntryValueTooLargeError"requiredValues
"InstructionEntryValueTooLargeError"actualBytesintegerrequiredmaxBytesintegerrequiredmessagestringrequiredIntegration.AttemptEncodedobject
objectattemptIDstringrequiredurlstringrequiredinstructionsstringrequiredmode"auto" | "code"requiredValues
"auto" | "code"timeobjectrequiredcreatednumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"expiresnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"Integration.AttemptStatusobject | object | object | object
object | object | object | objectobjectstatus"pending"requiredValues
"pending"timeobjectrequiredcreatednumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"expiresnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"or
objectstatus"complete"requiredValues
"complete"timeobjectrequiredcreatednumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"expiresnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"or
objectstatus"failed"requiredValues
"failed"messagestringrequiredtimeobjectrequiredcreatednumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"expiresnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"or
objectstatus"expired"requiredValues
"expired"timeobjectrequiredcreatednumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"expiresnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"Integration.CommandAttemptobject
objectattemptIDstringrequiredtimeobjectrequiredcreatednumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"expiresnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"Integration.CommandAttemptStatusobject | object | object | object
object | object | object | objectobjectstatus"pending"requiredValues
"pending"messagestringtimeobjectrequiredcreatednumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"expiresnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"or
objectstatus"complete"requiredValues
"complete"timeobjectrequiredcreatednumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"expiresnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"or
objectstatus"failed"requiredValues
"failed"messagestringrequiredtimeobjectrequiredcreatednumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"expiresnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"or
objectstatus"expired"requiredValues
"expired"timeobjectrequiredcreatednumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"expiresnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"Integration.CommandMethodobject
objectidstringrequiredtype"command"requiredValues
"command"labelstringrequiredcommandstring[]requiredItems
stringIntegration.EnvMethodobject
objecttype"env"requiredValues
"env"namesstring[]requiredItems
stringIntegration.Infoobject
objectidstringrequirednamestringrequiredmetadataobjectmethodsIntegration.Method[]requiredItemsIntegration.Method
connectionsConnection.Info[]requiredItemsConnection.Info
Integration.KeyMethodobject
objectIntegration.MethodIntegration.OAuthMethod | Integration.CommandMethod | Integration.KeyMethod | Integration.EnvMethod
Integration.OAuthMethod | Integration.CommandMethod | Integration.KeyMethod | Integration.EnvMethodIntegration.OAuthMethodobject
objectIntegrationAttemptNotFoundErrorEncodedobject
object_tag"IntegrationAttemptNotFoundError"requiredValues
"IntegrationAttemptNotFoundError"integrationIDstringrequiredattemptIDstringrequiredmessagestringrequiredIntegrationMethodNotFoundErrorEncodedobject
object_tag"IntegrationMethodNotFoundError"requiredValues
"IntegrationMethodNotFoundError"integrationIDstringrequiredmethodIDstringrequiredmessagestringrequiredIntegrationNotFoundErrorEncodedobject
object_tag"IntegrationNotFoundError"requiredValues
"IntegrationNotFoundError"integrationIDstringrequiredmessagestringrequiredInvalidCursorErrorEncodedobject
object_tag"InvalidCursorError"requiredValues
"InvalidCursorError"messagestringrequiredInvalidRequestErrorEncodedobject
object_tag"InvalidRequestError"requiredValues
"InvalidRequestError"messagestringrequiredkindstring | nullstringor
nullfieldstring | nullstringor
nullLocation.PublicInfoobject
objectdirectorystringrequiredprojectobjectrequiredidstringrequireddirectorystringrequiredcanonicalstringrequiredLocation.PublicRefobject
objectdirectorystringrequiredMcp.LocalConfigEncodedobject
objecttype"local"requiredValues
"local"commandstring[]requiredItems
stringcwdstringenvironmentobjectAdditional properties
stringdisabledbooleancodemodebooleantimeoutobjectstartupinteger> 0
cataloginteger> 0
executioninteger> 0
Mcp.OAuthConfigEncodedobject
objectclient_idstringclient_secretstringscopestringcallback_portintegermin 1, max 65535
redirect_uristringMcp.RemoteConfigEncodedobject
objecttype"remote"requiredValues
"remote"urlstringrequiredheadersobjectAdditional properties
stringoauthMcp.OAuthConfigEncoded | falseor
falseValues
falsedisabledbooleancodemodebooleantimeoutobjectstartupinteger> 0
cataloginteger> 0
executioninteger> 0
Mcp.Resourceobject
objectserverstringrequirednamestringrequireduristringrequireddescriptionstringmimeTypestringMcp.ResourceCatalogobject
objectresourcesMcp.Resource[]requiredItemsMcp.Resource
templatesMcp.ResourceTemplate[]requiredItemsMcp.ResourceTemplate
Mcp.ResourceTemplateobject
objectserverstringrequirednamestringrequireduriTemplatestringrequireddescriptionstringmimeTypestringMcp.Serverobject
objectnamestringrequiredstatusMcp.Status.Connected | Mcp.Status.Pending | Mcp.Status.Disabled | Mcp.Status.Failed | Mcp.Status.NeedsAuthrequiredintegrationIDstringMcp.Status.Connectedobject
objectstatus"connected"requiredValues
"connected"Mcp.Status.Disabledobject
objectstatus"disabled"requiredValues
"disabled"Mcp.Status.Failedobject
objectstatus"failed"requiredValues
"failed"errorstringrequiredMcp.Status.NeedsAuthobject
objectstatus"needs_auth"requiredValues
"needs_auth"Mcp.Status.Pendingobject
objectstatus"pending"requiredValues
"pending"McpServerNotFoundErrorEncodedobject
object_tag"McpServerNotFoundError"requiredValues
"McpServerNotFoundError"serverstringrequiredmessagestringrequiredMessageNotFoundErrorEncodedobject
object_tag"MessageNotFoundError"requiredValues
"MessageNotFoundError"sessionIDstringrequiredmessageIDstringrequiredmessagestringrequiredModel.Capabilitiesobject
objecttoolsbooleanrequiredinputstring[]requiredItems
stringoutputstring[]requiredItems
stringresponsesWebsocketsbooleanModel.Compatibilityobject
objectreasoningFieldModel.ReasoningFieldrequireReasoningbooleanmaxTokensFieldModel.MaxTokensFieldrequireFinishReasonbooleanrequireAssistantAfterToolbooleanModel.Costobject
objecttierobjecttype"context"requiredValues
"context"sizeintegerrequiredcacheobjectrequiredModel.Infoobject
objectidstringrequiredmodelIDstringrequiredproviderIDstringrequiredcanonicalstringfamilystringnamestringrequiredcompatibilityModel.CompatibilitypackagestringcompactionProvider.CompactionwebsocketbooleansettingsobjectheadersobjectAdditional properties
stringbodyobjectcapabilitiesModel.CapabilitiesvariantsModel.Variant[]requiredItemsModel.Variant
timeobjectrequiredreleasednumberrequiredcostModel.Cost[]requiredItemsModel.Cost
status"alpha" | "beta" | "deprecated" | "active"requiredValues
"alpha" | "beta" | "deprecated" | "active"enabledbooleanrequiredlimitobjectrequiredcontextintegerrequiredinputintegeroutputintegerrequiredModel.MaxTokensField"max_completion_tokens" | "max_tokens"
"max_completion_tokens" | "max_tokens"Values
"max_completion_tokens" | "max_tokens"Model.ReasoningField"reasoning" | "reasoning_content" | "reasoning_text" | string
"reasoning" | "reasoning_content" | "reasoning_text" | string"reasoning" | "reasoning_content" | "reasoning_text"Values
"reasoning" | "reasoning_content" | "reasoning_text"or
stringModel.Refobject
objectidstringrequiredproviderIDstringrequiredvariantstringModel.Variantobject
objectidstringrequiredsettingsobjectheadersobjectAdditional properties
stringbodyobjectMoney.USDnumber
numberMoney.USDPerMillionTokensnumber
numberPermission.Effect"allow" | "deny" | "ask"
"allow" | "deny" | "ask"Values
"allow" | "deny" | "ask"Permission.Reply"once" | "always" | "reject"
"once" | "always" | "reject"Values
"once" | "always" | "reject"Permission.Requestobject
objectidstringrequiredpattern ^per
sessionIDstringrequiredpattern ^ses
actionstringrequiredresourcesstring[]requiredItems
stringsavestring[]Items
stringmetadataobjectsourcePermission.SourcemessagestringPermission.Ruleobject
objectPermission.RulesetPermission.Rule[]
Permission.Rule[]ItemsPermission.Rule
Permission.Sourceobject
objectobjecttype"tool"requiredValues
"tool"messageIDstringrequiredidstringrequiredPermissionNotFoundErrorEncodedobject
object_tag"PermissionNotFoundError"requiredValues
"PermissionNotFoundError"requestIDstringrequiredmessagestringrequiredPermissionSaved.Infoobject
objectidstringrequiredprojectIDstringrequiredactionstringrequiredresourcestringrequiredPersistentPty.CreateInputobject
objectcommandstringargsstring[]requiredItems
stringcwdstringtitlestringrequiredenvobjectrequiredAdditional properties
stringsizeobjectcolsintegerrequired> 0
rowsintegerrequired> 0
PersistentPty.Handoffobject
objectdirectorystringrequiredinstanceIDstringrequiredticketstringrequiredexpiresAtnumber | "Infinity" | "-Infinity" | "NaN"requirednumberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"PersistentPty.Infoobject
objectidstringrequiredpattern ^pty
titlestringrequiredcommandstringrequiredargsstring[]requiredItems
stringcwdstringrequiredstatus"running" | "exited"requiredValues
"running" | "exited"pidintegerrequiredmin 0
exitCodeintegermin 0
sessionIDstringrequiredpattern ^ses
foregroundProcessstring | nullrequiredstringor
nullsizeobjectrequiredcolsintegerrequired> 0
rowsintegerrequired> 0
outputobjectrequiredheadintegerrequiredmin 0
tailintegerrequiredmin 0
PersistentPty.ReadLinesEncodedstring
stringPersistentPty.ReadResultobject
objectptyIDstringrequiredpattern ^pty
titlestringrequiredcwdstringrequiredforegroundProcessstring | nullrequiredstringor
nullscreenobjectrequiredtextstringrequiredcolsintegerrequired> 0
rowsintegerrequired> 0
cursorobjectrequiredxintegerrequiredmin 0
yintegerrequiredmin 0
PersistentPty.Snapshotobject
objecttextstringrequiredcheckpointstring<byte>requiredcursorobjectrequiredxintegerrequiredmin 0
yintegerrequiredmin 0
PersistentPty.UpdateInputobject
objectattachmentIDstringsizeobjectrequiredcolsintegerrequired> 0
rowsintegerrequired> 0
Plugin.Featuresobject
objectservertrueValues
truetuitrueValues
truerpctrueValues
truePlugin.Infoobject
objectPlugin.Sourceobject | object | object | object
object | object | object | objectobjecttype"builtin"requiredValues
"builtin"or
objecttype"package"requiredValues
"package"targetstringrequiredversionstringoutdatedtrueValues
trueupdatingtrueValues
trueor
objecttype"local"requiredValues
"local"pathstringrequiredor
objecttype"sdk"requiredValues
"sdk"Plugin.Stateobject | object
object | objectobjectstatus"active"requiredValues
"active"or
objectstatus"failed"requiredValues
"failed"errorstringrequiredrefstringProjectobject
objectidstringrequiredcanonicalstringrequiredvcsProject.VcsnamestringiconProject.IconcommandsProject.CommandstimeProject.Timesandboxesstring[]requiredItems
stringProject.Commandsobject
objectstartstringStartup script to run when creating a new workspace (worktree)
Project.Iconobject
objecturlstringoverridestringcolorstringProject.Timeobject
objectcreatedintegerrequiredmin 0
updatedintegerrequiredmin 0
Project.Vcsstring
stringpattern ^[a-z][a-z0-9._-]*$
ProjectNotFoundErrorEncodedobject
object_tag"ProjectNotFoundError"requiredValues
"ProjectNotFoundError"projectIDstringrequiredmessagestringrequiredPrompt.AgentAttachmentobject
objectnamestringrequiredmentionPrompt.MentionPrompt.Base64string
stringpattern ^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$
Prompt.FileAttachmentobject
objectdataPrompt.Base64mimestringrequiredsourcePrompt.FileSourcenamestringdescriptionstringmentionPrompt.MentionPrompt.FileSourceobject | object
object | objectobjecttype"inline"requiredValues
"inline"or
objecttype"uri"requiredValues
"uri"uristringrequiredPrompt.Mentionobject
objectstartnumberrequiredendnumberrequiredtextstringrequiredPrompt.SkillAttachmentobject
objectPromptInput.FileAttachmentobject
objectPromptInput.SkillAttachmentobject
objectidstringrequiredmentionPrompt.MentionProvider.Compactionobject | object
object | objectobjectmode"local"requiredValues
"local"or
objectmode"provider"requiredValues
"provider"thresholdinteger> 0
Provider.Infoobject
objectidstringrequiredcanonicalstringintegrationIDstringnamestringrequiredactivation"auto" | "enabled" | "disabled"requiredValues
"auto" | "enabled" | "disabled"packagestringrequiredcompactionProvider.CompactionwebsocketbooleansettingsobjectheadersobjectAdditional properties
stringbodyobjectProvider.Requestobject
objectProvider.Settingsobject
objectProviderNotFoundErrorEncodedobject
object_tag"ProviderNotFoundError"requiredValues
"ProviderNotFoundError"providerIDstringrequiredmessagestringrequiredPtyobject
objectidstringrequiredpattern ^pty
titlestringrequiredcommandstringrequiredargsstring[]requiredItems
stringcwdstringrequiredstatus"running" | "exited"requiredValues
"running" | "exited"pidintegerrequiredmin 0
exitCodeintegermin 0
PtyNotFoundErrorEncodedobject
object_tag"PtyNotFoundError"requiredValues
"PtyNotFoundError"ptyIDstringrequiredmessagestringrequiredPtyTicket.ConnectTokenobject
objectticketstringrequiredexpires_inintegerrequired> 0
Reference.GitSourceobject
objecttype"git"requiredValues
"git"repositorystringrequiredbranchstringReference.Infoobject
objectReference.LocalSourceobject
objecttype"local"requiredValues
"local"pathstringrequiredReference.SourceReference.LocalSource | Reference.GitSource
Reference.LocalSource | Reference.GitSourceRpc.Inputobject
objectinputobjectRpc.Outputobject
objectoutputobjectRpcErrorEncodedobject
object_tag"RpcError"requiredValues
"RpcError"typestringrequiredmessagestringrequireddataobject | nullobjector
nullRpcInternalErrorEncodedobject
object_tag"RpcInternalError"requiredValues
"RpcInternalError"type"rpc.internal" | "rpc.invalid_output"requiredValues
"rpc.internal" | "rpc.invalid_output"messagestringrequireddataobject | nullobjector
nullServerStatusobject
objectversionstringrequiredpidintegerrequiredmin 0
urlsstring[]requiredItems
stringSession.ForkBoundaryobject | object
object | objectobjecttype"before"requiredValues
"before"messageIDstringrequiredpattern ^msg_
or
objecttype"through"requiredValues
"through"messageIDstringrequiredpattern ^msg_
Session.Inbox.Compactionobject
objectidstringrequiredpattern ^msg_
sessionIDstringrequiredpattern ^ses
timeCreatednumberrequiredtype"compaction"requiredValues
"compaction"deliverySession.Inbox.DeliverySession.Inbox.CompactionPayloadobject | empty[]
object | empty[]objector
empty[]Session.Inbox.Delivery"steer" | "queue"
"steer" | "queue"Values
"steer" | "queue"Session.Inbox.InfoSession.Inbox.User | Session.Inbox.Synthetic | Session.Inbox.Compaction | Session.Inbox.Move
Session.Inbox.User | Session.Inbox.Synthetic | Session.Inbox.Compaction | Session.Inbox.MoveSession.Inbox.Moveobject
objectidstringrequiredpattern ^msg_
sessionIDstringrequiredpattern ^ses
timeCreatednumberrequiredtype"move"requiredValues
"move"deliverySession.Inbox.DeliverypayloadSession.Inbox.MovePayloadSession.Inbox.MovePayloadobject
objectSession.Inbox.Syntheticobject
objectidstringrequiredpattern ^msg_
sessionIDstringrequiredpattern ^ses
timeCreatednumberrequiredtype"synthetic"requiredValues
"synthetic"deliverySession.Inbox.DeliverySession.Inbox.SyntheticPayloadobject
objecttextstringrequireddescriptionstringmetadataobjectSession.Inbox.Userobject
objectidstringrequiredpattern ^msg_
sessionIDstringrequiredpattern ^ses
timeCreatednumberrequiredtype"user"requiredValues
"user"payloadSession.Inbox.UserPayloaddeliverySession.Inbox.DeliverySession.Inbox.UserPayloadobject
objecttextstringrequiredfilesPrompt.FileAttachment[]agentsPrompt.AgentAttachment[]skillsPrompt.SkillAttachment[]metadataobjectSession.Infoobject
objectidstringrequiredpattern ^ses
parentIDstringpattern ^ses
forkobjectsessionIDstringrequiredpattern ^ses
boundarySession.ForkBoundaryprojectIDstringrequiredagentstringmodelModel.RefcostMoney.USDtokensTokenUsage.Infooutcome"succeeded" | "failed" | "interrupted"Values
"succeeded" | "failed" | "interrupted"timeobjectrequiredcreatednumberrequiredupdatednumberrequiredidlenumberviewednumberarchivednumbertitlestringsubpathstringmetadataSession.MetadatapermissionsPermission.RulesetrevertSession.RevertlocationLocation.PublicRefSession.Message.AgentSelectedobject
objectidstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredtype"agent-switched"requiredValues
"agent-switched"agentstringrequiredpreviousstringSession.Message.Assistantobject
objectidstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredstreamednumbercompletednumbertype"assistant"requiredValues
"assistant"agentstringrequiredmodelModel.RefcontentSession.Message.Assistant.Text | Session.Message.Assistant.Reasoning | Session.Message.Assistant.Tool[]requiredItems
Session.Message.Assistant.Text | Session.Message.Assistant.Reasoning | Session.Message.Assistant.Toolsnapshotobjectstartstringendstringfilesstring[]Items
stringfinish"stop" | "length" | "tool-calls" | "content-filter" | "error" | "unknown"Values
"stop" | "length" | "tool-calls" | "content-filter" | "error" | "unknown"rawFinishstringproviderStateSession.Message.ProviderState_4costMoney.USDtokensTokenUsage.InfoSession.Message.Assistant.Reasoningobject
objecttype"reasoning"requiredValues
"reasoning"textstringrequiredtimeobjectcreatednumberrequiredcompletednumberSession.Message.Assistant.Retryobject
objectSession.Message.Assistant.Textobject
objectSession.Message.Assistant.Toolobject
objecttype"tool"requiredValues
"tool"idstringrequirednamestringrequiredexecutedbooleanproviderStateSession.Message.ProviderState_2providerResultStateSession.Message.ProviderState_3stateSession.Message.ToolState.Streaming | Session.Message.ToolState.Running | Session.Message.ToolState.Completed | Session.Message.ToolState.ErrorrequiredtimeobjectrequiredcreatednumberrequiredrannumbercompletednumberSession.Message.CompactionSession.Message.Compaction.Running | Session.Message.Compaction.Completed | Session.Message.Compaction.Failed
Session.Message.Compaction.Running | Session.Message.Compaction.Completed | Session.Message.Compaction.FailedSession.Message.Compaction.Completedobject
objecttype"compaction"requiredValues
"compaction"idstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredstatus"completed"requiredValues
"completed"reason"auto" | "manual"requiredValues
"auto" | "manual"modelModel.RefproviderStateSession.Message.ProviderState_5summarystringrequiredrecentstringrequiredproviderContextSession.ProviderContextcostMoney.USDtokensTokenUsage.InfoSession.Message.Compaction.Failedobject
objecttype"compaction"requiredValues
"compaction"idstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredstatus"failed"requiredValues
"failed"reason"auto" | "manual"requiredValues
"auto" | "manual"costMoney.USDtokensTokenUsage.InfoSession.Message.Compaction.Runningobject
objecttype"compaction"requiredValues
"compaction"idstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredstatus"running"requiredValues
"running"reason"auto" | "manual"requiredValues
"auto" | "manual"summarystringrequiredrecentstringrequiredSession.Message.Idleobject
objectidstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredtype"idle"requiredValues
"idle"outcome"succeeded" | "failed" | "interrupted"requiredValues
"succeeded" | "failed" | "interrupted"Session.Message.InfoSession.Message.AgentSelected | Session.Message.ModelSelected | Session.Message.LocationSwitched | Session.Message.User | Session.Message.Synthetic | Session.Message.System | Session.Message.Skill | Session.Message.Shell | Session.Message.Assistant | Session.Message.Compaction | Session.Message.Idle
Session.Message.AgentSelected | Session.Message.ModelSelected | Session.Message.LocationSwitched | Session.Message.User | Session.Message.Synthetic | Session.Message.System | Session.Message.Skill | Session.Message.Shell | Session.Message.Assistant | Session.Message.Compaction | Session.Message.IdleSession.Message.LocationSwitchedobject
objectidstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredtype"location-switched"requiredValues
"location-switched"projectIDstringsubpathstringlocationLocation.PublicRefpreviousobject | nullobjector
nullSession.Message.ModelSelectedobject
Session.Message.ProviderStateobject
objectSession.Message.ProviderState_1object
objectSession.Message.ProviderState_2object
objectSession.Message.ProviderState_3object
objectSession.Message.ProviderState_4object
objectSession.Message.ProviderState_5object
objectSession.Message.Shellobject
objectidstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredcompletednumbertype"shell"requiredValues
"shell"shellIDstringrequiredpattern ^sh_
commandstringrequiredstatus"running" | "exited" | "timeout" | "killed"requiredValues
"running" | "exited" | "timeout" | "killed"exitnumber | "Infinity" | "-Infinity" | "NaN"numberor
"Infinity" | "-Infinity" | "NaN"Values
"Infinity" | "-Infinity" | "NaN"outputobjectoutputstringrequiredcursorintegerrequiredmin 0
sizeintegerrequiredmin 0
truncatedbooleanrequiredSession.Message.Skillobject
objectidstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredtype"skill"requiredValues
"skill"skillstringrequirednamestringrequiredtextstringrequiredSession.Message.Syntheticobject
objectidstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredtextstringrequireddescriptionstringtype"synthetic"requiredValues
"synthetic"Session.Message.Systemobject
objectidstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredtype"system"requiredValues
"system"textstringrequireddescriptionstringSession.Message.ToolState.Completedobject
objectstatus"completed"requiredValues
"completed"inputobjectrequiredcontentmetadataobjectSession.Message.ToolState.Errorobject
objectstatus"error"requiredValues
"error"inputobjectrequiredcontentmetadataobjectSession.Message.ToolState.Runningobject
objectstatus"running"requiredValues
"running"inputobjectrequiredmetadataobjectrequiredSession.Message.ToolState.Streamingobject
objectstatus"streaming"requiredValues
"streaming"inputstringrequiredSession.Message.Userobject
objectidstringrequiredpattern ^msg_
metadataobjecttimeobjectrequiredcreatednumberrequiredtextstringrequiredfilesPrompt.FileAttachment[]agentsPrompt.AgentAttachment[]skillsPrompt.SkillAttachment[]type"user"requiredValues
"user"Session.Metadataobject
objectSession.ProviderContextobject
objectSession.ProviderContext.Provenanceobject
objectproviderIDstringrequiredproviderstringrequiredmodelIDstringrequiredroutestringrequiredprotocolstringrequiredendpointstringrequiredSession.Revertobject
objectmessageIDstringrequiredpattern ^msg_
partIDstringsnapshotstringfilesFileDiff.Info[]ItemsFileDiff.Info
Session.StructuredErrorobject
objecttypestringrequiredmessagestringrequiredstatusintegermin 100, max 599
SessionActiveobject
objecttype"running"requiredValues
"running"SessionBusyErrorEncodedobject
object_tag"SessionBusyError"requiredValues
"SessionBusyError"sessionIDstringrequiredmessagestringrequiredSessionGenerateResponseobject
objectdataobjectrequiredtextstringrequiredSessionInterruptResponseobject
objectinterruptedbooleanrequiredWhether an active execution owned by this OpenCode process was interrupted.
SessionLogItemEncodedstring
stringSessionMessagesResponseobject
objectdataSession.Message.Info[]requiredItemsSession.Message.Info
cursorobjectrequiredpreviousstring | nullstringor
nullnextstring | nullstringor
nullSessionNotFoundErrorEncodedobject
object_tag"SessionNotFoundError"requiredValues
"SessionNotFoundError"sessionIDstringrequiredmessagestringrequiredSessionStats.Activityobject
objectdatestringrequiredstepsintegerrequiredmin 0
SessionStats.Infoobject
objectrangeobjectrequiredfromnumberrequiredtonumberrequiredsessionsintegerrequiredmin 0
subagentsintegerrequiredmin 0
promptsintegerrequiredmin 0
stepsintegerrequiredmin 0
tokensTokenUsage.InfocostMoney.USDtoolsSessionStats.ToolsactiveDaysintegerrequiredmin 0
streakintegerrequiredmin 0
activitySessionStats.Activity[]requiredmodelsSessionStats.ModelUsage[]requiredSessionStats.ModelUsageobject
objectSessionStats.ToolTotalsobject
objectcallsintegerrequiredmin 0
succeededintegerrequiredmin 0
failedintegerrequiredmin 0
unfinishedintegerrequiredmin 0
SessionStats.ToolUsageobject
objectnamestringrequiredcallsintegerrequiredmin 0
succeededintegerrequiredmin 0
failedintegerrequiredmin 0
unfinishedintegerrequiredmin 0
durationP50numberSessionStats.Toolsobject | object | object
object | object | objectobjectmode"none"requiredValues
"none"or
objectmode"summary"requiredValues
"summary"totalsSessionStats.ToolTotalsor
objectmode"detail"requiredValues
"detail"totalsSessionStats.ToolTotalsusageSessionStats.ToolUsage[]requiredSessionTransfer.Dataobject
objectinfoSession.InfomessagesSession.Message.Info[]requiredItemsSession.Message.Info
SessionsResponseobject
objectdataSession.Info[]requiredItemsSession.Info
cursorobjectrequiredpreviousstring | nullstringor
nullnextstring | nullstringor
nullShell.Infoobject
objectidstringrequiredpattern ^sh_
status"running" | "exited" | "timeout" | "killed"requiredValues
"running" | "exited" | "timeout" | "killed"commandstringrequiredcwdstringrequiredshellstringrequiredfilestringrequiredpidintegermin 0
exitnumbermetadataobjectrequiredtimeobjectrequiredstartednumberrequiredcompletednumberShellNotFoundErrorEncodedobject
object_tag"ShellNotFoundError"requiredValues
"ShellNotFoundError"idstringrequiredmessagestringrequiredSkill.Infoobject
objectidstringrequirednamestringrequireddescriptionstringautoinvokebooleanpathstringrequiredcontentstringrequiredSkillNotFoundErrorEncodedobject
object_tag"SkillNotFoundError"requiredValues
"SkillNotFoundError"skillstringrequiredmessagestringrequiredTokenUsage.Infoobject
objectinputnumberrequiredoutputnumberrequiredreasoningnumberrequiredcacheobjectrequiredreadnumberrequiredwritenumberrequiredTool.ContentTool.TextContent | Tool.FileContent
Tool.TextContent | Tool.FileContentTool.FileContentobject
objecttype"file"requiredValues
"file"uristringrequiredmimestringrequirednamestring | nullstringor
nullTool.TextContentobject
objecttype"text"requiredValues
"text"textstringrequiredUnauthorizedErrorEncodedobject
object_tag"UnauthorizedError"requiredValues
"UnauthorizedError"messagestringrequiredUnknownErrorEncodedobject
object_tag"UnknownError"requiredValues
"UnknownError"messagestringrequiredrefstring | nullstringor
nullV2EventEncodedstring
stringVcs.Baseobject
objectnamestringrequiredrefstringrequiredsource"reflog" | "default"requiredValues
"reflog" | "default"Vcs.Branchobject
objectcurrentstringdefaultstringVcs.BranchListstring[]
string[]Items
stringVcs.FileStatusobject
objectfilestringrequiredadditionsintegerrequiredmin 0
deletionsintegerrequiredmin 0
status"added" | "deleted" | "modified"requiredValues
"added" | "deleted" | "modified"Vcs.Infoobject
objectbranchVcs.BranchVcs.Mode"working" | "branch" | "committed"
"working" | "branch" | "committed"Values
"working" | "branch" | "committed"WebSearch.Providerobject
objectidstringrequirednamestringrequiredWebSearch.ResponseEncodedobject
objectproviderIDstringrequiredresultsWebSearch.Result[]requiredItemsWebSearch.Result
WebSearch.Resultobject
objecturlstringrequiredtitlestringcontentstringtimeobjectrequiredpublishednumberWorktree.CreateInputobject
objectstrategystringfromstringbranchstringdirectorystringnamestringWorktree.Directoryobject
objectdirectorystringrequiredstrategystringWorktree.Infoobject
objectdirectorystringrequiredWorktree.ListWorktree.Directory[]
Worktree.Directory[]ItemsWorktree.Directory
Worktree.RemoveInputobject
objectdirectorystringrequiredforcebooleanrequiredWorktreeErrorEncodedobject
objectname"WorktreeError"requiredValues
"WorktreeError"dataobjectrequiredmessagestringrequiredforceRequiredboolean | nullbooleanor
null