A Python SDK for the opencode REST API,
pinned to opencode server version 1.15.5 and generated by
liblab from the current OpenAPI specification.
The official Python SDK at anomalyco/opencode-sdk-python
(PyPI: opencode-ai) has been stuck on v0.1.0-alpha.36 since
2025-08-27 and only exposes a small slice of the early API surface
(/session, /session/{id}/message, /file, /find, /app, /event).
It does not cover the surface a modern opencode server (1.15+) actually exposes — the table below shows what's missing from anomalyco but present here:
| Endpoint / event | anomalyco (opencode-ai) |
this SDK (opencode-api) |
|---|---|---|
GET /session/status |
❌ | ✅ |
GET /session/{id}/todo |
❌ | ✅ |
GET /session/{id}/diff |
❌ | ✅ |
GET /question + reply |
❌ | ✅ |
GET /permission + reply |
❌ | ✅ |
POST /session/{id}/prompt_async |
❌ | ✅ |
Bus events: session.status, session.idle, todo.updated, session.diff, question.asked, permission.asked, etc. |
❌ | ✅ |
If you need anything beyond the alpha endpoint set, use this SDK.
- SDK version:
1.15.5(tracks opencode server release) - Targets opencode server:
1.15.5 - Distribution name on import:
opencode_api(PyPI dist name:opencode-api)
Distinct from opencode-ai (anomalyco) — pick one or the other, not both.
opencode api
- Setup & Configuration
- Authentication
- Setting a Custom Timeout
- Sample Usage
- Async Usage
- Services
- Models
This SDK is compatible with the following versions: Python >= 3.9
This SDK is not currently published on PyPI — install directly from this repository. Pin to the tag that matches your opencode server version.
Using uv (recommended)
uv add "opencode-api @ git+https://github.com/that-ambuj/opencode-python-sdk.git@v1.15.5"Or for a one-off install into the current environment:
uv pip install "git+https://github.com/that-ambuj/opencode-python-sdk.git@v1.15.5"pip3 install "git+https://github.com/that-ambuj/opencode-python-sdk.git@v1.15.5"dependencies = [
"opencode-api @ git+https://github.com/that-ambuj/opencode-python-sdk.git@v1.15.5",
]opencode-api @ git+https://github.com/that-ambuj/opencode-python-sdk.git@v1.15.5
uv pip install "git+https://github.com/that-ambuj/opencode-python-sdk.git"
# or
pip3 install "git+https://github.com/that-ambuj/opencode-python-sdk.git"The Opencode API uses an Access Token for authentication.
This token must be provided to authenticate your requests to the API.
When you initialize the SDK, you can set the access token as follows:
Opencode(
access_token="YOUR_ACCESS_TOKEN",
timeout=10000
)If you need to set or update the access token after initializing the SDK, you can use:
sdk.set_access_token("YOUR_ACCESS_TOKEN")You can set a custom timeout for the SDK's HTTP requests as follows:
from opencode_api import Opencode
sdk = Opencode(timeout=10000)Below is a comprehensive example demonstrating how to authenticate and call a simple endpoint:
from opencode_api import Opencode
sdk = Opencode(
access_token="YOUR_ACCESS_TOKEN",
timeout=10000
)
result = sdk.global_.global_health()
print(result)The SDK includes an Async Client for making asynchronous API requests. This is useful for applications that need non-blocking operations, like web servers or apps with a graphical user interface.
import asyncio
from opencode_api import OpencodeAsync
sdk = OpencodeAsync(
access_token="YOUR_ACCESS_TOKEN",
timeout=10000
)
async def main():
result = await sdk.global_.global_health()
print(result)
asyncio.run(main())The SDK provides various services to interact with the API.
Below is a list of all available services with links to their detailed documentation:
The SDK includes several models that represent the data structures used in API requests and responses. These models help in organizing and managing the data efficiently.
Below is a list of all available models with links to their detailed documentation:
Union types allow you to specify that a variable can have more than one type. This is particularly useful when a function can accept multiple types of inputs. The Union type hint is used for this purpose.
You can call service method with an instance of TypeA, TypeB, or a dictionary that can be converted to an instance of either type.
# Model Definition
ParamType = Union[TypeA, TypeB]
# Service Method
def service_method(param: ParamType):
...
## Usage
type_a = TypeA(key="value")
type_b = TypeB(key="value")
sdk.service.service_method(type_a)
sdk.service.service_method(type_b)
sdk.service.service_method({"key": "value"})You cannot create an instance of a Union type itself. Instead, pass an instance of one of the types in the Union, or a dictionary that can be converted to one of those types.