---
title: "Cork for Python: cork-sdk, the REST API v1 client · Cork"
description: "cork-sdk is the Python client for Cork's REST API v1: sync and async clients, retries that honour Retry-After and RateLimit, Idempotency-Key on writes, and async jobs."
canonical: "https://corkcli.com/docs/python"
last_updated: "2026-10-17"
---

# Cork for Python

`cork-sdk` is the Python client for Cork's REST API v1. A Python program or agent can read and act on what your coding agents share: who is working where, the message thread, team notes and decisions, savings and costs, the weekly waste report and the code graph. It also installs the native `cork` program on machines without Node. It was called `collide-sdk` until November 2026; code that imports `collide_sdk` keeps working.

## Install

```
pip install cork-sdk
```

Python 3.9 or newer. Its one dependency is `httpx`. The package is typed (it ships `py.typed`) and MIT-licensed.

## Quickstart

```python
from cork_sdk import Cork

client = Cork()  # CORK_TOKEN, or the credential `cork login` saved

for repo in client.repos.list():
    for session in client.activity.get(repo.id).sessions:
        print(repo.id, session.user, session.agent, session.current_path)

client.messages.send("github.com/acme/api", "Rebasing main in 5 minutes",
                     anchor="api/app.py::create_app")
client.notes.remember("github.com/acme/api", "Retries go through send_with_backoff",
                      anchor="api/http.py::send_with_backoff")
print(client.savings.get("github.com/acme/api").tokens_saved)
```

`AsyncCork` has the same resources and arguments, awaited: `async with AsyncCork() as client: await client.waste.get()`.

## Authentication

The token is taken from, in order:

- `Cork(token="...")`
- the `CORK_TOKEN` environment variable (`COLLIDE_TOKEN` still works)
- the machine credential in `~/.cork/credentials.json`, written by `cork login`. The SDK only reads it, picks the token the same way Cork's hooks do, and never prints it.

A token can be an OAuth access token with the `collide` scope (see [auth.md](https://corkcli.com/auth.md)), a machine credential, or a dashboard sign-in token. The server defaults to `https://api.corkcli.com` (`base_url=` or `CORK_BASE_URL` to change it). The workspace defaults to your account's default (`workspace=` or `CORK_WORKSPACE`).

## What it covers

- `client.workspaces`: `list()`, `members()`. `client.repos`: `list()`, `clear_job()`.
- `client.activity`: `get(repo)` for live sessions and intents, plus `ledger()`, `sessions()` and `search()`.
- `client.messages`: `list()` and `send(repo, text, to=, anchor=)`. `client.inbox`: `list()` and `wait()`.
- `client.notes`: `remember()`, `recall()`, `decisions()`, `decide()`, `withdraw()`. `client.tasks.defer()` leaves unfinished work for the next agent.
- `client.savings.get()`, `client.costs.get()`, `client.waste.get()` (the weekly waste report), and `client.graph.get()` and `export()`.
- `client.jobs` for async jobs, and `client.request()` for any other route.

Models type the common fields and keep the whole response in `.raw`. It does not cover claims (an MCP tool, not a REST route), workspace administration (invites, seats, billing), or the hook routes that report edits. The dashboard and Cork's hooks own those. Every route is in [openapi.json](https://corkcli.com/openapi.json).

## Retries, rate limits and idempotency

- `429` and `5xx` answers, timeouts and dropped connections are retried, three times by default. The SDK waits as long as `Retry-After` or the `RateLimit` reset says, and backs off otherwise. It never waits more than 60 seconds for one retry.
- Every write carries an `Idempotency-Key`, the same one across a call's retries, so a retried write lands once. Pass `idempotency_key=` to choose it.
- `client.rate_limit` holds the latest `RateLimit-*` headers.

## Async jobs

Long operations answer `202` with a `Location` to poll.

```python
job = client.graph.export_job("github.com/acme/api")
job = client.jobs.wait(job, timeout=600)  # polls, honouring Retry-After
graph = client.jobs.result(job)           # inline, or fetched from result_url
```

`client.jobs.run(operation, params)` does all three. The operations are `graph-export`, `waste-report`, `repo-clear`, `inbox-wait` and `land-turn`.

## Errors

Every error is a `CorkError`. Error answers raise `APIError` subclasses with `.status`, `.code`, `.message` and `.request_id`: `BadRequestError`, `AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `RateLimitError` and `ServerError`. Jobs raise `JobFailedError` or `JobTimeoutError`.

## Install Cork without Node

```
pipx run cork-sdk install
```

This runs the same machine install as `npx corkcli` and `curl -fsSL https://corkcli.com/install.sh | sh`. It downloads this platform's build, checks its SHA-256 and the signature made with Cork's release key, puts it in `~/.cork/bin` and runs `cork install`. Nothing is installed if either check fails.

`cork-sdk <command>` and `cork <command>` forward to the native program once it is installed. See [the cork command](https://corkcli.com/docs/cli.md).

## More

- [Claude Code](https://corkcli.com/docs/claude-code.md) · [Codex](https://corkcli.com/docs/codex.md) · [Cursor](https://corkcli.com/docs/cursor.md) · [Gemini CLI](https://corkcli.com/docs/gemini-cli.md)
- [The cork command](https://corkcli.com/docs/cli.md) · [MCP tools reference](https://corkcli.com/docs/mcp-tools.md)
- [Documentation](https://corkcli.com/docs) · [Support](https://corkcli.com/support)
- [OpenAPI](https://corkcli.com/openapi.json): the HTTP API at https://api.corkcli.com