Python client

carbon-client is the officially-supported Python client for the Carbon control-plane API. It is a thin sync + async wrapper over httpx with typed dataclass responses for the top control-plane endpoints.

Install

pip install carbon-client

Requires Python 3.9+. See the carbon-client PyPI page.

Quickstart (sync)

from carbon_client import CarbonClient, CarbonError

carbon = CarbonClient(
    base_url="http://localhost:4000",
    api_key="ck_live_xxx",  # optional; sent as `Authorization: Bearer <key>`
)

try:
    for project in carbon.list_projects():
        print(project.id, project.slug)
except CarbonError as err:
    print(f"[{err.status}] {err.code}: {err.message}")

Quickstart (async)

import asyncio
from carbon_client import CarbonClient

async def main() -> None:
    async with CarbonClient(base_url="http://localhost:4000") as carbon:
        health = await carbon.aget_health()
        print(health.status)

asyncio.run(main())

Hand-written surface

The client ships with hand-written, typed methods for the ten most-used control-plane endpoints:

Method	Endpoint
`list_projects`	`GET /v1/projects`
`create_project`	`POST /v1/projects`
`get_project`	`GET /v1/projects/{id}`
`list_snapshots`	`GET /v1/snapshots`
`list_emulators`	`GET /v1/emulators`
`list_events`	`GET /v1/events`
`list_api_keys`	`GET /v1/api-keys`
`create_api_key`	`POST /v1/api-keys`
`list_usage`	`GET /v1/usage`
`get_health`	`GET /v1/health/live`

Every method has an a-prefixed async twin (alist_projects, aget_health, …).

Anything else

For endpoints not in the hand-written surface, use request / arequest to talk to any path — the parsed JSON body comes back directly, and non-2xx responses raise CarbonError:

data = carbon.request("GET", "/v1/feature-flags")

Errors

All non-2xx responses raise CarbonError(status, code, message, details).