Resources

Every resource is reachable as an attribute of the client, for example client.session. Each sync class below has an Async twin with the same methods, which return awaitables. The method list with HTTP routes is also in api.md.

AgentResource

AgentResource(client: Opencode)

Operations under client.agent (OpenCode agent).

with_raw_response cached property

with_raw_response: AgentResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: AgentResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> AgentListResponse

List agents.

Retrieve currently registered agents.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/agent

get

get(
    agent_id: AgentID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> AgentGetResponse

Get agent.

Retrieve a single currently registered agent.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
AgentNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/agent/:agentID

CommandResource

CommandResource(client: Opencode)

Operations under client.command (OpenCode command).

with_raw_response cached property

with_raw_response: CommandResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    CommandResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> CommandListResponse

List commands.

Retrieve currently registered commands.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/command

ConfigResource

ConfigResource(client: Opencode)

Operations under client.config (OpenCode config).

with_raw_response cached property

with_raw_response: ConfigResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: ConfigResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

get

get(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[ConfigEntry]

Get configuration.

Return configuration documents and discovery sources for the requested location, from lowest to highest priority.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/config

shells

shells(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[ConfigShellOption]

List available shells.

Return shells available to terminal and agent execution.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/config/shell

update

update(
    *,
    shell: str | None,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Update global configuration.

Patch supported fields in the highest-precedence global configuration document.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

PATCH /api/experimental/config

CredentialResource

CredentialResource(client: Opencode)

Operations under client.credential (OpenCode credential).

with_raw_response cached property

with_raw_response: CredentialResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    CredentialResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[CredentialEntry]

List credentials.

List every stored integration credential, including its secret value.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

GET /api/credential

create

create(
    *,
    integration_id: IntegrationID,
    value: CredentialValue,
    id: CredentialID | NotGiven = NOT_GIVEN,
    label: str | NotGiven = NOT_GIVEN,
    activate: bool | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> CredentialEntry

Create credential.

Store an integration credential. It becomes the integration's active credential unless activate is false and the integration already has one. Fails with a conflict when the requested ID already exists.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ConflictError	The server answered 409.

POST /api/credential

update

update(
    credential_id: CredentialID,
    *,
    label: str,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Update credential.

Update a stored credential label.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

PATCH /api/credential/:credentialID

activate

activate(
    credential_id: CredentialID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Activate credential.

Activate a stored integration credential.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

POST /api/credential/:credentialID/activate

remove

remove(
    credential_id: CredentialID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Remove credential.

Remove a stored integration credential.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

DELETE /api/credential/:credentialID

DebugLocationResource

DebugLocationResource(client: Opencode)

Operations under client.debug.location (OpenCode debug.location).

with_raw_response cached property

with_raw_response: DebugLocationResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    DebugLocationResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[LocationPublicRef]

List loaded locations.

List locations currently loaded by the server.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

GET /api/debug/location

evict

evict(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Evict a loaded location.

Dispose the requested location's cached services so its next use boots them fresh.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

DELETE /api/debug/location

DebugResource

DebugResource(client: Opencode)

Operations under client.debug (OpenCode debug).

location cached property

location: DebugLocationResource

Operations under client.debug.location.

with_raw_response cached property

with_raw_response: DebugResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: DebugResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

EventResource

EventResource(client: Opencode)

Operations under client.event (OpenCode event).

with_raw_response cached property

with_raw_response: EventResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: EventResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

subscribe

subscribe(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> Stream[Event]

Subscribe 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.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

GET /api/event

ExperimentalPersistentPtyResource

ExperimentalPersistentPtyResource(client: Opencode)

Operations under client.experimental.persistent_pty (OpenCode experimental.persistentPty).

with_raw_response cached property

with_raw_response: (
    ExperimentalPersistentPtyResourceWithRawResponse
)

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    ExperimentalPersistentPtyResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

read

read(
    session_id: SessionID,
    *,
    lines: PersistentPtyReadLines
    | NotGiven
    | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PersistentPtyReadResult | None

Read 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.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ServiceUnavailableError	The server answered 503.

GET /api/experimental/session/:sessionID/terminal/read

list

list(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[PersistentPtyInfo]

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ServiceUnavailableError	The server answered 503.

GET /api/experimental/session/:sessionID/terminal

create

create(
    session_id: SessionID,
    *,
    args: Sequence[str],
    title: str,
    env: Mapping[str, str],
    command: str | NotGiven = NOT_GIVEN,
    cwd: str | NotGiven = NOT_GIVEN,
    size: ExperimentalPersistentPtyCreateSize
    | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PersistentPtyInfo

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ServiceUnavailableError	The server answered 503.

POST /api/experimental/session/:sessionID/terminal

shutdown

shutdown(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ServiceUnavailableError	The server answered 503.

POST /api/experimental/persistent-pty/shutdown

handoff

handoff(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ExperimentalPersistentPtyHandoffResponse

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ServiceUnavailableError	The server answered 503.

POST /api/experimental/persistent-pty/handoff

get

get(
    pty_id: PtyID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PersistentPtyInfo

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
PtyNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

GET /api/experimental/persistent-pty/:ptyID

update

update(
    pty_id: PtyID,
    *,
    size: ExperimentalPersistentPtyUpdateSize,
    attachment_id: str | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PersistentPtyInfo

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
PtyNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

PUT /api/experimental/persistent-pty/:ptyID

snapshot

snapshot(
    pty_id: PtyID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PersistentPtySnapshot

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
PtyNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

GET /api/experimental/persistent-pty/:ptyID/snapshot

remove

remove(
    pty_id: PtyID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
PtyNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

DELETE /api/experimental/persistent-pty/:ptyID

connect_token

connect_token(
    pty_id: PtyID,
    *,
    x_opencode_ticket: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PtyTicketConnectToken

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ForbiddenError	The server answered 403.
PtyNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

POST /api/experimental/persistent-pty/:ptyID/connect-token

ExperimentalResource

ExperimentalResource(client: Opencode)

Operations under client.experimental (OpenCode experimental).

persistent_pty cached property

persistent_pty: ExperimentalPersistentPtyResource

Operations under client.experimental.persistent_pty.

with_raw_response cached property

with_raw_response: ExperimentalResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    ExperimentalResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

FileResource

FileResource(client: Opencode)

Operations under client.file (OpenCode file).

with_raw_response cached property

with_raw_response: FileResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: FileResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

read

read(
    path: str,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> bytes

Read file.

Stream one file relative to the requested location with ETag, Last-Modified, and single-range HTTP Range support (206 Partial Content, 416 Range Not Satisfiable, and 304 Not Modified; multi-range and malformed Range headers fall back to 200).

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
RemoteFileNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/fs/read/*

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    path: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> FileListResponse

List 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.

Parameters:

Name	Type	Description	Default
path	str | NotGiven | None	An absolute path or a path relative to the requested location. Defaults to the location directory.	NOT_GIVEN

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
RemoteFileNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/fs/list

find

find(
    *,
    query: str,
    location: Location | NotGiven | None = NOT_GIVEN,
    type: OpenEnum[Literal["file", "directory"]]
    | NotGiven
    | None = NOT_GIVEN,
    limit: int | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> FileFindResponse

Find files.

Find recursively ranked filesystem entries relative to the requested location.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/fs/find

write

write(
    *,
    path: str,
    payload: bytes,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> FileWriteResponse

Write file.

Write the raw request body to an absolute path or a path relative to the requested location, creating parent directories, and return the resolved absolute path. Unlike read, the target is not confined to the location. Experimental: may change without compatibility guarantees.

This endpoint is experimental in OpenCode and may change without notice.

Parameters:

Name	Type	Description	Default
path	str	An absolute path or a path relative to the requested location. Missing parent directories are created.	required

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

POST /api/experimental/fs/write

FormResource

FormResource(client: Opencode)

Operations under client.form (OpenCode form).

with_raw_response cached property

with_raw_response: FormResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: FormResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> FormListResponse

List pending forms.

Retrieve pending forms for a location.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/form

GenerateResource

GenerateResource(client: Opencode)

Operations under client.generate (OpenCode generate).

with_raw_response cached property

with_raw_response: GenerateResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    GenerateResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

text

text(
    *,
    prompt: str,
    model: ModelRef | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> GenerateTextResponseData

Generate 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.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

POST /api/experimental/generate

IntegrationWellknownResource

IntegrationWellknownResource(client: Opencode)

Operations under client.integration.wellknown (OpenCode integration.wellknown).

with_raw_response cached property

with_raw_response: (
    IntegrationWellknownResourceWithRawResponse
)

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    IntegrationWellknownResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

add

add(
    *,
    url: str,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Add wellknown integration.

Discover and persist an experimental wellknown integration source.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

POST /api/experimental/integration/wellknown

IntegrationConnectResource

IntegrationConnectResource(client: Opencode)

Operations under client.integration.connect (OpenCode integration.connect).

with_raw_response cached property

with_raw_response: IntegrationConnectResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    IntegrationConnectResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

key

key(
    integration_id: IntegrationID,
    *,
    key: str,
    location: Location | NotGiven | None = NOT_GIVEN,
    answer: FormAnswer | NotGiven | None = NOT_GIVEN,
    label: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Connect with key.

Run a key authentication method and store the resulting credential.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
IntegrationNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/integration/:integrationID/connect/key

external

external(
    integration_id: IntegrationID,
    *,
    method_id: IntegrationMethodID,
    location: Location | NotGiven | None = NOT_GIVEN,
    answer: FormAnswer | NotGiven | None = NOT_GIVEN,
    label: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Connect with external credentials.

Run an external authentication method and store a reference to its credential source.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
IntegrationNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/integration/:integrationID/connect/external

IntegrationOauthResource

IntegrationOauthResource(client: Opencode)

Operations under client.integration.oauth (OpenCode integration.oauth).

with_raw_response cached property

with_raw_response: IntegrationOauthResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    IntegrationOauthResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

connect

connect(
    integration_id: IntegrationID,
    *,
    method_id: IntegrationMethodID,
    location: Location | NotGiven | None = NOT_GIVEN,
    answer: FormAnswer | NotGiven | None = NOT_GIVEN,
    label: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> IntegrationOauthConnectResponse

Begin OAuth connection.

Start an OAuth attempt and return the authorization details.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

POST /api/integration/:integrationID/connect/oauth

status

status(
    integration_id: IntegrationID,
    attempt_id: IntegrationAttemptID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> IntegrationOauthStatusResponse

Get OAuth attempt status.

Poll the current status of an OAuth attempt.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
IntegrationNotFoundError	The server answered 404.
IntegrationAttemptNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/integration/:integrationID/connect/oauth/:attemptID

complete

complete(
    integration_id: IntegrationID,
    attempt_id: IntegrationAttemptID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    code: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Complete OAuth connection.

Complete a code-based OAuth attempt and store the resulting credential.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
IntegrationNotFoundError	The server answered 404.
IntegrationAttemptNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/integration/:integrationID/connect/oauth/:attemptID/complete

cancel

cancel(
    integration_id: IntegrationID,
    attempt_id: IntegrationAttemptID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Cancel OAuth connection.

Cancel an OAuth attempt and release its resources.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

DELETE /api/integration/:integrationID/connect/oauth/:attemptID

IntegrationCommandResource

IntegrationCommandResource(client: Opencode)

Operations under client.integration.command (OpenCode integration.command).

with_raw_response cached property

with_raw_response: IntegrationCommandResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    IntegrationCommandResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

connect

connect(
    integration_id: IntegrationID,
    *,
    method_id: IntegrationMethodID,
    location: Location | NotGiven | None = NOT_GIVEN,
    label: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> IntegrationCommandConnectResponse

Begin command connection.

Start a command authentication attempt.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
IntegrationNotFoundError	The server answered 404.
IntegrationMethodNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/integration/:integrationID/connect/command

status

status(
    integration_id: IntegrationID,
    attempt_id: IntegrationAttemptID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> IntegrationCommandStatusResponse

Get command attempt status.

Poll the current status and output of a command authentication attempt.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
IntegrationNotFoundError	The server answered 404.
IntegrationAttemptNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/integration/:integrationID/connect/command/:attemptID

cancel

cancel(
    integration_id: IntegrationID,
    attempt_id: IntegrationAttemptID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Cancel command connection.

Cancel a command authentication attempt and terminate its process.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

DELETE /api/integration/:integrationID/connect/command/:attemptID

IntegrationResource

IntegrationResource(client: Opencode)

Operations under client.integration (OpenCode integration).

wellknown cached property

wellknown: IntegrationWellknownResource

Operations under client.integration.wellknown.

connect cached property

connect: IntegrationConnectResource

Operations under client.integration.connect.

oauth cached property

oauth: IntegrationOauthResource

Operations under client.integration.oauth.

command cached property

command: IntegrationCommandResource

Operations under client.integration.command.

with_raw_response cached property

with_raw_response: IntegrationResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    IntegrationResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> IntegrationListResponse

List integrations.

Retrieve available integrations and their authentication methods.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/integration

get

get(
    integration_id: IntegrationID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> IntegrationGetResponse

Get integration.

Retrieve one integration and its authentication methods.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
IntegrationNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/integration/:integrationID

LocationResource

LocationResource(client: Opencode)

Operations under client.location (OpenCode location).

with_raw_response cached property

with_raw_response: LocationResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    LocationResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

get

get(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> LocationPublicInfo

Get location.

Resolve the requested location or the server default location.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/location

reload

reload(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Reload configuration.

Shut down and rebuild every loaded location. Pending permissions and forms are cancelled; running sessions continue with fresh services at the next step boundary. Emits location.shutdown for client recovery and responds once all replacement builds settle.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ServiceUnavailableError	The server answered 503.

POST /api/location/reload

McpResourceResource

McpResourceResource(client: Opencode)

Operations under client.mcp.resource (OpenCode mcp.resource).

with_raw_response cached property

with_raw_response: McpResourceResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    McpResourceResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

catalog

catalog(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> McpResourceCatalogResponse

List MCP resources.

Retrieve resources and resource templates from connected MCP servers.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/mcp/resource

McpResource

McpResource(client: Opencode)

Operations under client.mcp (OpenCode mcp).

resource cached property

resource: McpResourceResource

Operations under client.mcp.resource.

with_raw_response cached property

with_raw_response: McpResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: McpResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> McpListResponse

List MCP servers.

Retrieve configured MCP servers and their connection status.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/mcp

add

add(
    server: str,
    *,
    config: McpAddConfig,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Add MCP server.

Add an MCP server at runtime or replace an existing one, connecting it immediately.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

PUT /api/experimental/mcp/:server

remove

remove(
    server: str,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Remove MCP server.

Stop an MCP server and remove it from the runtime set until restart.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
McpServerNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

DELETE /api/experimental/mcp/:server

connect

connect(
    server: str,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Connect MCP server.

Connect an MCP server at runtime, overriding a disabled configuration until restart.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
McpServerNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/experimental/mcp/:server/connect

disconnect

disconnect(
    server: str,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Disconnect MCP server.

Disconnect an MCP server at runtime, removing its tools until reconnected.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
McpServerNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/experimental/mcp/:server/disconnect

MessageResource

MessageResource(client: Opencode)

Operations under client.message (OpenCode message).

with_raw_response cached property

with_raw_response: MessageResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    MessageResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    session_id: SessionID,
    *,
    limit: int | NotGiven | None = NOT_GIVEN,
    order: OpenEnum[Literal["asc", "desc"]]
    | NotGiven
    | None = NOT_GIVEN,
    cursor: str | NotGiven | None = NOT_GIVEN,
    type: OpenEnum[
        Literal[
            "agent-switched",
            "model-switched",
            "location-switched",
            "user",
            "synthetic",
            "system",
            "skill",
            "shell",
            "assistant",
            "compaction",
            "idle",
        ]
    ]
    | NotGiven
    | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SyncCursorPage[SessionMessageInfo]

Get 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.

Parameters:

Name	Type	Description	Default
limit	int | NotGiven | None	Maximum number of messages to return. When omitted, the endpoint returns its default page size.	NOT_GIVEN
order	OpenEnum[Literal['asc', 'desc']] | NotGiven | None	Message order for the first page. Use desc for newest first or asc for oldest first.	NOT_GIVEN
cursor	str | NotGiven | None	Opaque pagination cursor returned as cursor.previous or cursor.next in the previous response. Do not combine with order.	NOT_GIVEN
type	OpenEnum[Literal['agent-switched', 'model-switched', 'location-switched', 'user', 'synthetic', 'system', 'skill', 'shell', 'assistant', 'compaction', 'idle']] | NotGiven | None	Filter by message type before pagination. When omitted, all message types are returned. Pass the same type when following cursors.	NOT_GIVEN

Raises:

Type	Description
InvalidCursorError	The server answered 400.
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
UnknownError	The server answered 500.

GET /api/session/:sessionID/message

MigrationV1Resource

MigrationV1Resource(client: Opencode)

Operations under client.migration.v1 (OpenCode migration.v1).

with_raw_response cached property

with_raw_response: MigrationV1ResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    MigrationV1ResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

status

status(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> (
    MigrationV1StatusResponseOption1
    | MigrationV1StatusResponseOption2
    | MigrationV1StatusResponseOption3
)

Get V1 migration status.

Return the progress of the V1 to V2 session history migration.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

GET /api/experimental/migration/v1

MigrationResource

MigrationResource(client: Opencode)

Operations under client.migration (OpenCode migration).

v1 cached property

v1: MigrationV1Resource

Operations under client.migration.v1.

with_raw_response cached property

with_raw_response: MigrationResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    MigrationResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

ModelResource

ModelResource(client: Opencode)

Operations under client.model (OpenCode model).

with_raw_response cached property

with_raw_response: ModelResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: ModelResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ModelListResponse

List models.

Retrieve the current snapshot of available models ordered by release date. The snapshot may precede initial plugin settlement.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

GET /api/model

default

default(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ModelDefaultResponse

Get default model.

Retrieve the model used when a session has no explicit model selection.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

GET /api/model/default

PermissionRequestResource

PermissionRequestResource(client: Opencode)

Operations under client.permission.request (OpenCode permission.request).

with_raw_response cached property

with_raw_response: PermissionRequestResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    PermissionRequestResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PermissionRequestListResponse

List pending permission requests.

Retrieve pending permission requests for a location.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/permission/request

PermissionSavedResource

PermissionSavedResource(client: Opencode)

Operations under client.permission.saved (OpenCode permission.saved).

with_raw_response cached property

with_raw_response: PermissionSavedResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    PermissionSavedResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    project_id: ProjectID | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[PermissionSavedInfo]

List saved permissions.

Retrieve saved permissions, optionally filtered by project.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/permission/saved

update

update(
    id: PermissionSavedID,
    *,
    action: str | NotGiven | None = NOT_GIVEN,
    resource: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PermissionSavedInfo

Update saved permission.

Change the action or resource of a saved permission. Fails with a conflict when the project already has a saved permission with the same action and resource.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
PermissionSavedNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
ConflictError	The server answered 409.

PATCH /api/permission/saved/:id

remove

remove(
    id: PermissionSavedID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Remove saved permission.

Remove a saved permission by ID.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

DELETE /api/permission/saved/:id

PermissionResource

PermissionResource(client: Opencode)

Operations under client.permission (OpenCode permission).

request_ cached property

request_: PermissionRequestResource

Operations under client.permission.request.

saved cached property

saved: PermissionSavedResource

Operations under client.permission.saved.

with_raw_response cached property

with_raw_response: PermissionResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    PermissionResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

create

create(
    session_id: SessionID,
    *,
    action: str,
    resources: Sequence[str],
    id: PermissionID | NotGiven | None = NOT_GIVEN,
    save: Sequence[str] | NotGiven = NOT_GIVEN,
    metadata: Mapping[str, Any] | NotGiven = NOT_GIVEN,
    source: PermissionSource | NotGiven = NOT_GIVEN,
    agent: AgentID | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PermissionCreateResponse

Create permission request.

Evaluate and, when approval is required, create a permission request for a session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/session/:sessionID/permission

list

list(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[PermissionRequest]

List session permission requests.

Retrieve pending permission requests owned by a session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/session/:sessionID/permission

get

get(
    session_id: SessionID,
    request_id: PermissionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PermissionRequest

Get permission request.

Retrieve a pending permission request owned by a session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
PermissionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/session/:sessionID/permission/:requestID

reply

reply(
    session_id: SessionID,
    request_id: PermissionID,
    *,
    decision: PermissionReply,
    message: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Reply to pending permission request.

Respond to a pending permission request owned by a session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
PermissionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/session/:sessionID/permission/:requestID/reply

PluginResource

PluginResource(client: Opencode)

Operations under client.plugin (OpenCode plugin).

with_raw_response cached property

with_raw_response: PluginResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: PluginResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PluginListResponse

List plugins.

Retrieve enabled server plugins and their current status.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/plugin

check

check(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    target: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PluginCheckResponse

Check plugin updates.

Check one or all package plugins for available updates.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

POST /api/plugin/check

update

update(
    *,
    targets: Sequence[str],
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Update plugins.

Update package plugins concurrently and notify active locations to reload them. Responds once every update has finished; fails when any update fails.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

POST /api/plugin/update

ProjectResource

ProjectResource(client: Opencode)

Operations under client.project (OpenCode project).

with_raw_response cached property

with_raw_response: ProjectResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    ProjectResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    archived: bool | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[Project]

List projects.

List known projects. Archived projects are excluded unless archived=true.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/project

update

update(
    project_id: ProjectID,
    *,
    canonical: AbsolutePath | NotGiven = NOT_GIVEN,
    name: str | NotGiven = NOT_GIVEN,
    icon: ProjectIcon | NotGiven = NOT_GIVEN,
    commands: ProjectCommands | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> Project

Update project.

Update the project canonical directory, display metadata, and workspace commands.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ProjectNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

PATCH /api/project/:projectID

ProviderResource

ProviderResource(client: Opencode)

Operations under client.provider (OpenCode provider).

with_raw_response cached property

with_raw_response: ProviderResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    ProviderResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ProviderListResponse

List providers.

Retrieve active AI providers so clients can show provider availability and configuration.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

GET /api/provider

get

get(
    provider_id: ProviderID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ProviderGetResponse

Get provider.

Retrieve a single AI provider so clients can inspect its availability and endpoint settings.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ProviderNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

GET /api/provider/:providerID

PtyConnectResource

PtyConnectResource(client: Opencode)

Operations under client.pty.connect (OpenCode pty.connect).

with_raw_response cached property

with_raw_response: PtyConnectResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    PtyConnectResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

token

token(
    pty_id: PtyID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    x_opencode_ticket: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PtyConnectTokenResponse

Create PTY WebSocket token.

Create a short-lived single-use ticket for opening a PTY WebSocket connection.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ForbiddenError	The server answered 403.
PtyNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/pty/:ptyID/connect-token

PtyResource

PtyResource(client: Opencode)

Operations under client.pty (OpenCode pty).

connect cached property

connect: PtyConnectResource

Operations under client.pty.connect.

with_raw_response cached property

with_raw_response: PtyResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: PtyResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PtyListResponse

List PTY sessions.

List PTY sessions for a location, including exited sessions retained until removal.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/pty

create

create(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    command: str | NotGiven = NOT_GIVEN,
    args: Sequence[str] | NotGiven = NOT_GIVEN,
    cwd: str | NotGiven = NOT_GIVEN,
    title: str | NotGiven = NOT_GIVEN,
    env: Mapping[str, str] | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PtyCreateResponse

Create PTY session.

Create a pseudo-terminal session for a location.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

POST /api/pty

get

get(
    pty_id: PtyID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PtyGetResponse

Get PTY session.

Get one PTY session, including its exit code once exited.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
PtyNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/pty/:ptyID

update

update(
    pty_id: PtyID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    title: str | NotGiven = NOT_GIVEN,
    size: PtyUpdateSize | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PtyUpdateResponse

Update PTY session.

Update the title or viewport size of one PTY session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
PtyNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

PUT /api/pty/:ptyID

remove

remove(
    pty_id: PtyID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Remove PTY session.

Terminate and remove one PTY session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
PtyNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

DELETE /api/pty/:ptyID

ReferenceResource

ReferenceResource(client: Opencode)

Operations under client.reference (OpenCode reference).

with_raw_response cached property

with_raw_response: ReferenceResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    ReferenceResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ReferenceListResponse

List references.

List references available in the requested location.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/reference

RpcResource

RpcResource(client: Opencode)

Operations under client.rpc (OpenCode rpc).

with_raw_response cached property

with_raw_response: RpcResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: RpcResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

call

call(
    rpc_id: str,
    method: str,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    input: Any | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> RpcOutput

Call a plugin RPC.

Dispatch a method to the currently registered RPC at the requested location.

Raises:

Type	Description
RpcError	The server answered 400.
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
RpcInternalError	The server answered 500.

POST /api/rpc/:rpcID/:method

ServerResource

ServerResource(client: Opencode)

Operations under client.server (OpenCode server).

with_raw_response cached property

with_raw_response: ServerResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: ServerResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

info

info(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ServerInfo

Get server info.

Return the server identity, connection URLs, paths, and readiness status.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

GET /api/info

pair

pair(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PairingCode

Create pairing code.

Create a short-lived, single-use code for a /auth/connect/:code pairing link.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

POST /api/pair

connect

connect(
    code: str,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> PairingSession

Redeem pairing code.

Redeem a pairing code. Browsers receive a session cookie and a redirect to the web app; requests that accept JSON receive a session token to use as the password.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

GET /auth/connect/:code

SessionRevertResource

SessionRevertResource(client: Opencode)

Operations under client.session.revert (OpenCode session.revert).

with_raw_response cached property

with_raw_response: SessionRevertResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    SessionRevertResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

stage

stage(
    session_id: SessionID,
    *,
    message_id: SessionMessageID,
    files: bool | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionRevert

Stage session revert.

Stage or move a reversible session boundary and optionally apply its file changes.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
MessageNotFoundError	The server answered 404.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
SessionBusyError	The server answered 409.
UnknownError	The server answered 500.

POST /api/session/:sessionID/revert/stage

clear

clear(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Clear staged revert.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
SessionBusyError	The server answered 409.
UnknownError	The server answered 500.

DELETE /api/session/:sessionID/revert

commit

commit(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Commit staged revert.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
SessionBusyError	The server answered 409.

POST /api/session/:sessionID/revert/commit

SessionInboxResource

SessionInboxResource(client: Opencode)

Operations under client.session.inbox (OpenCode session.inbox).

with_raw_response cached property

with_raw_response: SessionInboxResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    SessionInboxResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[SessionInboxInfo]

List session inbox.

List durable enqueued session work not yet delivered, ordered by enqueue sequence. Includes user, synthetic, compaction, and move items.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.

GET /api/session/:sessionID/inbox

cancel

cancel(
    session_id: SessionID,
    inbox_id: SessionMessageID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Cancel inbox input.

Cancel an inbox item that has not yet been delivered. Unavailable items are a no-op.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.

DELETE /api/session/:sessionID/inbox/:inboxID

update

update(
    session_id: SessionID,
    inbox_id: SessionMessageID,
    *,
    delivery: SessionInboxDelivery,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Update inbox item.

Change a pending inbox item's delivery mode. Steering wakes session execution.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
ConflictError	The server answered 409.

PATCH /api/session/:sessionID/inbox/:inboxID

SessionInstructionsEntryResource

SessionInstructionsEntryResource(client: Opencode)

Operations under client.session.instructions.entry (OpenCode session.instructions.entry).

with_raw_response cached property

with_raw_response: (
    SessionInstructionsEntryResourceWithRawResponse
)

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    SessionInstructionsEntryResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[InstructionEntryInfo]

List instruction entries.

List API-managed instruction entries attached to the session.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/experimental/session/:sessionID/instructions/entries

put

put(
    session_id: SessionID,
    key: InstructionEntryKey,
    *,
    value: Any,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Put instruction entry.

Attach or replace one durable instruction entry. Changes announce as updates at the next step boundary.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
InstructionEntryValueTooLargeError	The server answered 413.

PUT /api/experimental/session/:sessionID/instructions/entries/:key

remove

remove(
    session_id: SessionID,
    key: InstructionEntryKey,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Remove instruction entry.

Remove one instruction entry; the removal is announced to the model at the next step boundary.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

DELETE /api/experimental/session/:sessionID/instructions/entries/:key

SessionInstructionsResource

SessionInstructionsResource(client: Opencode)

Operations under client.session.instructions (OpenCode session.instructions).

entry cached property

entry: SessionInstructionsEntryResource

Operations under client.session.instructions.entry.

with_raw_response cached property

with_raw_response: (
    SessionInstructionsResourceWithRawResponse
)

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    SessionInstructionsResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

SessionMessageResource

SessionMessageResource(client: Opencode)

Operations under client.session.message (OpenCode session.message).

with_raw_response cached property

with_raw_response: SessionMessageResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    SessionMessageResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

get

get(
    session_id: SessionID,
    message_id: SessionMessageID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionMessageInfo

Get session message.

Retrieve one projected message owned by the Session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
MessageNotFoundError	The server answered 404.

GET /api/session/:sessionID/message/:messageID

SessionFormResource

SessionFormResource(client: Opencode)

Operations under client.session.form (OpenCode session.form).

with_raw_response cached property

with_raw_response: SessionFormResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    SessionFormResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    session_id: str,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[FormInfo]

List session forms.

Retrieve pending forms for a session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/session/:sessionID/form

create

create(
    session_id: str,
    *,
    title: str,
    fields: FormFields,
    id: FormID | NotGiven | None = NOT_GIVEN,
    metadata: FormMetadata | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> FormInfo

Create session form.

Create a form for a session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
ConflictError	The server answered 409.

POST /api/session/:sessionID/form

get

get(
    session_id: str,
    form_id: FormID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> FormDetail

Get session form.

Retrieve a form and its current state for a session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
FormNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/session/:sessionID/form/:formID

reply

reply(
    session_id: str,
    form_id: FormID,
    *,
    answer: FormAnswer,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Reply to form.

Submit an answer to a pending form.

Raises:

Type	Description
FormInvalidAnswerError	The server answered 400.
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
FormNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
FormAlreadySettledError	The server answered 409.

POST /api/session/:sessionID/form/:formID/reply

cancel

cancel(
    session_id: str,
    form_id: FormID,
    *,
    message: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Cancel form.

Cancel a pending form, optionally telling the asker why it was not answered.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
FormNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
FormAlreadySettledError	The server answered 409.

DELETE /api/session/:sessionID/form/:formID

SessionResource

SessionResource(client: Opencode)

Operations under client.session (OpenCode session).

revert cached property

revert: SessionRevertResource

Operations under client.session.revert.

inbox cached property

inbox: SessionInboxResource

Operations under client.session.inbox.

instructions cached property

instructions: SessionInstructionsResource

Operations under client.session.instructions.

message cached property

message: SessionMessageResource

Operations under client.session.message.

form cached property

form: SessionFormResource

Operations under client.session.form.

with_raw_response cached property

with_raw_response: SessionResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    SessionResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    limit: int | NotGiven | None = NOT_GIVEN,
    order: OpenEnum[Literal["asc", "desc"]]
    | NotGiven
    | None = NOT_GIVEN,
    search: str | NotGiven | None = NOT_GIVEN,
    parent_id: SessionID | NotGiven | None = NOT_GIVEN,
    archived: bool | NotGiven | None = NOT_GIVEN,
    directory: AbsolutePath | NotGiven | None = NOT_GIVEN,
    project: ProjectID | NotGiven | None = NOT_GIVEN,
    subpath: RelativePath | NotGiven | None = NOT_GIVEN,
    cursor: SessionsCursor | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SyncCursorPage[SessionInfo]

List 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.

Parameters:

Name	Type	Description	Default
limit	int | NotGiven | None	Maximum number of sessions to return. Defaults to the newest 50 sessions.	NOT_GIVEN
order	OpenEnum[Literal['asc', 'desc']] | NotGiven | None	Session order for the first page. Use desc for newest first or asc for oldest first.	NOT_GIVEN
parent_id	SessionID | NotGiven | None	Filter by parent session. Use null to return only root sessions.	NOT_GIVEN
archived	bool | NotGiven | None	Filter by archive state. Use true to return only archived sessions or false to exclude them. Omit to include both.	NOT_GIVEN

Raises:

Type	Description
InvalidCursorError	The server answered 400.
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

GET /api/session

stats

stats(
    *,
    from_: float
    | OpenEnum[Literal["Infinity", "-Infinity", "NaN"]]
    | NotGiven
    | None = NOT_GIVEN,
    to: float
    | OpenEnum[Literal["Infinity", "-Infinity", "NaN"]]
    | NotGiven
    | None = NOT_GIVEN,
    project: ProjectID | NotGiven | None = NOT_GIVEN,
    timezone: str | NotGiven | None = NOT_GIVEN,
    tools: OpenEnum[Literal["none", "summary", "detail"]]
    | NotGiven
    | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionStatsInfo

Get session statistics.

Aggregate local session activity, usage, and tool reliability for a time range.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

GET /api/experimental/session/stats

create

create(
    *,
    id: SessionID | NotGiven | None = NOT_GIVEN,
    parent_id: SessionID | NotGiven | None = NOT_GIVEN,
    title: str | NotGiven | None = NOT_GIVEN,
    agent: AgentID | NotGiven | None = NOT_GIVEN,
    model: ModelRef | NotGiven | None = NOT_GIVEN,
    location: LocationPublicRef
    | NotGiven
    | None = NOT_GIVEN,
    metadata: SessionMetadata | NotGiven | None = NOT_GIVEN,
    permissions: PermissionRuleset
    | NotGiven
    | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionInfo

Create session.

Create a session at the requested location. A parentID creates a linked child session at its parent's location.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.

POST /api/session

import_

import_(
    *,
    info: SessionInfo,
    messages: Sequence[Any],
    location: LocationPublicRef
    | NotGiven
    | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionInfo

Import session.

Import a projected session transcript at the requested location. Accepts transcripts exported by earlier releases. If parentID is supplied, the parent session must already exist; import parents before children.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
ConflictError	The server answered 409.

POST /api/experimental/session/import

export

export(
    session_id: SessionID,
    *,
    sanitize: bool | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionTransferData

Export session.

Export a complete projected session transcript.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
UnknownError	The server answered 500.

GET /api/experimental/session/:sessionID/export

active

active(
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> dict[str, Any]

List active sessions.

Retrieve foreground Session drains currently owned by this OpenCode process. Sessions absent from the result are inactive.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.

GET /api/session/active

get

get(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionInfo

Get session.

Retrieve a session by ID.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.

GET /api/session/:sessionID

remove

remove(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Delete session.

Delete a session and its child sessions.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.

DELETE /api/session/:sessionID

fork

fork(
    session_id: SessionID,
    *,
    before: SessionMessageID | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionInfo

Fork session.

Create a child session by copying projected history before a message. Omit before to copy the full history.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
MessageNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/session/:sessionID/fork

switch_agent

switch_agent(
    session_id: SessionID,
    *,
    agent: AgentID,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Switch session agent.

Switch the agent used by subsequent provider turns.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/session/:sessionID/agent

switch_model

switch_model(
    session_id: SessionID,
    *,
    model: ModelRef,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Switch session model.

Switch the model used by subsequent provider turns.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/session/:sessionID/model

update

update(
    session_id: SessionID,
    *,
    title: str | NotGiven | None = NOT_GIVEN,
    metadata: SessionMetadata | NotGiven | None = NOT_GIVEN,
    permissions: PermissionRuleset
    | NotGiven
    | None = NOT_GIVEN,
    archived: bool | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Update session.

Update mutable session properties.

Parameters:

Name	Type	Description	Default
archived	bool | NotGiven | None	Archive the session with true or restore it with false. Repeating the current state is a no-op.	NOT_GIVEN

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

PATCH /api/session/:sessionID

move

move(
    session_id: SessionID,
    *,
    directory: AbsolutePath,
    delivery: SessionInboxDelivery
    | NotGiven
    | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Move session.

Move a session to another project directory at the requested delivery boundary.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.

POST /api/session/:sessionID/move

prompt

prompt(
    session_id: SessionID,
    *,
    text: str,
    id: SessionMessageID | NotGiven | None = NOT_GIVEN,
    files: Sequence[PromptInputFileAttachment]
    | NotGiven = NOT_GIVEN,
    agents: Sequence[PromptAgentAttachment]
    | NotGiven = NOT_GIVEN,
    skills: Sequence[PromptInputSkillAttachment]
    | NotGiven = NOT_GIVEN,
    metadata: Mapping[str, Any] | NotGiven = NOT_GIVEN,
    delivery: SessionInboxDelivery
    | NotGiven
    | None = NOT_GIVEN,
    resume: bool | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionInboxUser

Send message.

Durably admit one session input and schedule agent-loop execution unless resume is false.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
ConflictError	The server answered 409.

POST /api/session/:sessionID/prompt

command

command(
    session_id: SessionID,
    *,
    name: str,
    text: str,
    files: Sequence[PromptInputFileAttachment]
    | NotGiven = NOT_GIVEN,
    agents: Sequence[PromptAgentAttachment]
    | NotGiven = NOT_GIVEN,
    skills: Sequence[PromptInputSkillAttachment]
    | NotGiven = NOT_GIVEN,
    delivery: SessionInboxDelivery
    | NotGiven
    | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Run command.

Execute a slash command callback immediately.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
CommandNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
CommandExecutionError	The server answered 500.

POST /api/session/:sessionID/command

skill

skill(
    session_id: SessionID,
    *,
    id: SkillID,
    resume: bool | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Activate skill.

Activate a skill for a session by appending a skill message and resuming execution.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
SkillNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/experimental/session/:sessionID/skill

synthetic

synthetic(
    session_id: SessionID,
    *,
    text: str,
    id: SessionMessageID | NotGiven | None = NOT_GIVEN,
    description: str | NotGiven | None = NOT_GIVEN,
    metadata: Mapping[str, Any] | NotGiven = NOT_GIVEN,
    delivery: SessionInboxDelivery
    | NotGiven
    | None = NOT_GIVEN,
    resume: bool | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionInboxSynthetic

Add synthetic message.

Durably admit synthetic session input and schedule execution unless resume is false.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
ConflictError	The server answered 409.

POST /api/session/:sessionID/synthetic

shell

shell(
    session_id: SessionID,
    *,
    command: str,
    id: SessionMessageID | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Run 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.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/session/:sessionID/shell

compact

compact(
    session_id: SessionID,
    *,
    id: SessionMessageID | NotGiven | None = NOT_GIVEN,
    delivery: SessionInboxDelivery
    | NotGiven
    | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionInboxCompaction

Compact session.

Durably admit a session compaction request. Steers by default: it runs at the next step boundary instead of waiting behind queued prompts.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
ConflictError	The server answered 409.

POST /api/session/:sessionID/compact

wait

wait(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Wait for session.

Wait for a session agent loop to become idle.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

POST /api/experimental/session/:sessionID/wait

context

context(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[SessionMessageInfo]

Get session context.

Retrieve the active context messages for a session (all messages after the last compaction).

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
UnknownError	The server answered 500.

GET /api/session/:sessionID/context

diff

diff(
    session_id: SessionID,
    *,
    from_: SessionMessageID | NotGiven | None = NOT_GIVEN,
    to: SessionMessageID | NotGiven | None = NOT_GIVEN,
    context: int | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> list[FileDiffInfo]

Diff 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.

Parameters:

Name	Type	Description	Default
from_	SessionMessageID | NotGiven | None	User message whose turn to diff. Defaults to the turn of the newest user message.	NOT_GIVEN
to	SessionMessageID | NotGiven | None	Later user message whose turn ends the range. Defaults to the turn of from alone.	NOT_GIVEN
context	int | NotGiven | None	Unchanged lines around each hunk. Omit for full-file patches.	NOT_GIVEN

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
MessageNotFoundError	The server answered 404.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
UnknownError	The server answered 500.

GET /api/session/:sessionID/diff

generate

generate(
    session_id: SessionID,
    *,
    prompt: str,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionGenerateResponseData

Generate text from session context.

Generate transient text from the current session context without mutating session history.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

POST /api/session/:sessionID/generate

log

log(
    session_id: SessionID,
    *,
    after: EventSeq | NotGiven | None = NOT_GIVEN,
    follow: bool | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> Stream[SessionLogItem]

Read the session log.

Experimental durable session event log. Reads events after an exclusive aggregate sequence and continues with live events when follow=true.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.

GET /api/experimental/session/:sessionID/log

interrupt

interrupt(
    session_id: SessionID,
    *,
    resume: bool | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SessionInterruptResponse

Interrupt 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 resume=true, execution resumes pending steering input and next-in-line control items (manual compaction, moves) while queued prompts remain parked.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/session/:sessionID/interrupt

background

background(
    session_id: SessionID,
    *,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Background blocking session tools.

Move active foreground backgroundable tools for this session into background observation. Idle requests are a no-op.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

POST /api/session/:sessionID/background

environment

environment(
    session_id: SessionID,
    *,
    variables: Mapping[str, str],
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Set session environment.

Replace the process environment used by local shell commands for this session.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.

PUT /api/session/:sessionID/environment

view

view(
    session_id: SessionID,
    *,
    idle: float,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

View session.

Mark the idle transition observed by the viewer as viewed.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
SessionNotFoundError	The server answered 404.

POST /api/session/:sessionID/view

ShellResource

ShellResource(client: Opencode)

Operations under client.shell (OpenCode shell).

with_raw_response cached property

with_raw_response: ShellResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: ShellResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ShellListResponse

List running shell commands.

List currently running shell commands for a location. Exited commands are not included.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/shell

create

create(
    *,
    command: str,
    location: Location | NotGiven | None = NOT_GIVEN,
    cwd: str | NotGiven = NOT_GIVEN,
    timeout_: int | NotGiven = NOT_GIVEN,
    metadata: Mapping[str, Any] | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ShellCreateResponse

Run shell command.

Spawn one non-interactive shell command for a location. Combined stdout/stderr is captured to a file pageable via output.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

POST /api/shell

get

get(
    id: ShellID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ShellGetResponse

Get shell command.

Get one shell command, including its status and exit code once exited.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ShellNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/shell/:id

output

output(
    id: ShellID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    cursor: int | NotGiven | None = NOT_GIVEN,
    limit: int | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> ShellOutputResponse

Read shell output.

Page through captured combined output by absolute byte cursor.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ShellNotFoundError	The server answered 404.
LocationNotFoundError	The server answered 404.

GET /api/shell/:id/output

remove

remove(
    id: ShellID,
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Remove shell command.

Terminate and remove one shell command and its retained output.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

DELETE /api/shell/:id

SkillResource

SkillResource(client: Opencode)

Operations under client.skill (OpenCode skill).

with_raw_response cached property

with_raw_response: SkillResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: SkillResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> SkillListResponse

List skills.

Retrieve currently registered skills.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/skill

VcsBranchResource

VcsBranchResource(client: Opencode)

Operations under client.vcs.branch (OpenCode vcs.branch).

with_raw_response cached property

with_raw_response: VcsBranchResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    VcsBranchResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    search: str | NotGiven | None = NOT_GIVEN,
    limit: int | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> VcsBranchListResponse

VCS branches.

List local and remote branches available at the requested location.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/vcs/branch

VcsResource

VcsResource(client: Opencode)

Operations under client.vcs (OpenCode vcs).

branch cached property

branch: VcsBranchResource

Operations under client.vcs.branch.

with_raw_response cached property

with_raw_response: VcsResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: VcsResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

init

init(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    provider: str | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Initialize VCS repository.

Initialize a repository using the selected VCS provider in a markerless project's directory and refresh its location services. Omitting provider defaults to git; built-in git and hg providers support initialization. An unknown provider returns 400; a registered provider without init returns 501.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ConflictError	The server answered 409.
VcsInitNotSupportedError	The server answered 501.
ServiceUnavailableError	The server answered 503.

POST /api/vcs/init

get

get(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> VcsGetResponse

VCS info.

Get current and default branch information for the requested location.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/vcs

base

base(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> VcsBaseResponse

VCS 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.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

GET /api/vcs/base

status

status(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> VcsStatusResponse

VCS status.

List uncommitted working-copy changes relative to the requested location.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.

GET /api/vcs/status

diff

diff(
    *,
    mode: VcsMode,
    location: Location | NotGiven | None = NOT_GIVEN,
    base: str | NotGiven | None = NOT_GIVEN,
    context: int | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> VcsDiffResponse

VCS 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.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

GET /api/vcs/diff

VoiceResource

VoiceResource(client: Opencode)

Operations under client.voice (OpenCode voice).

with_raw_response cached property

with_raw_response: VoiceResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: VoiceResourceWithStreamingResponse

Same methods, returning a context manager over the HTTP response without reading the body.

session

session(
    *,
    model: str,
    transport: VoiceTransportInput,
    session: Mapping[str, Any]
    | NotGiven
    | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> VoiceSessionResponseData

Create voice session.

Create a server-brokered voice session using the server's configured provider credentials and return the WebRTC SDP answer or WebSocket ephemeral token.

This endpoint is experimental in OpenCode and may change without notice.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

POST /api/experimental/voice/session

WebsearchResource

WebsearchResource(client: Opencode)

Operations under client.websearch (OpenCode websearch).

with_raw_response cached property

with_raw_response: WebsearchResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    WebsearchResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

providers

providers(
    *,
    location: Location | NotGiven | None = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> WebsearchProvidersResponse

List web search providers.

Return the registered web search providers.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

GET /api/websearch/provider

query

query(
    *,
    query: str,
    location: Location | NotGiven | None = NOT_GIVEN,
    provider_id: WebSearchID | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> WebsearchQueryResponse

Search the web.

Run one web search through the selected provider. Specify a provider to override the configured default.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
LocationNotFoundError	The server answered 404.
ServiceUnavailableError	The server answered 503.

POST /api/websearch

WorktreeResource

WorktreeResource(client: Opencode)

Operations under client.worktree (OpenCode worktree).

with_raw_response cached property

with_raw_response: WorktreeResourceWithRawResponse

Same methods, returning the raw HTTP response; call .parse() on it for the usual value.

with_streaming_response cached property

with_streaming_response: (
    WorktreeResourceWithStreamingResponse
)

Same methods, returning a context manager over the HTTP response without reading the body.

list

list(
    *,
    project_id: ProjectID,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> WorktreeList

List worktrees.

Return the project's saved worktree inventory without loading configuration or running discovery.

Raises:

Type	Description
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ProjectNotFoundError	The server answered 404.

GET /api/worktree

create

create(
    *,
    project_id: ProjectID,
    from_: AbsolutePath | NotGiven = NOT_GIVEN,
    branch: str | NotGiven = NOT_GIVEN,
    directory: AbsolutePath | NotGiven = NOT_GIVEN,
    name: str | NotGiven = NOT_GIVEN,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> WorktreeInfo

Create worktree.

Load the project's canonical configuration, create a local worktree using its selected strategy, then run the project's setup script.

Raises:

Type	Description
WorktreeError	The server answered 400.
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ProjectNotFoundError	The server answered 404.

POST /api/worktree

remove

remove(
    *,
    project_id: ProjectID,
    directory: AbsolutePath,
    force: bool,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Remove worktree.

Load the project's canonical configuration and remove a saved worktree using its recorded strategy.

Raises:

Type	Description
WorktreeError	The server answered 400.
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ProjectNotFoundError	The server answered 404.

DELETE /api/worktree

refresh

refresh(
    *,
    project_id: ProjectID,
    extra_headers: Headers | None = None,
    extra_query: Query | None = None,
    extra_body: Body | None = None,
    timeout: Timeout | NotGiven = NOT_GIVEN,
) -> None

Refresh worktrees.

Load the project's canonical configuration, discover worktrees across known checkout roots using all available strategies, and reconcile saved state.

Raises:

Type	Description
WorktreeError	The server answered 400.
InvalidRequestError	The server answered 400.
UnauthorizedError	The server answered 401.
ProjectNotFoundError	The server answered 404.

POST /api/worktree/refresh