---
title: Python SDK
description: Manage Capawesome Cloud from Python with the official SDK — apps, builds, channels, deployments, and more, fully typed with Pydantic models.
---

# Python SDK

The official Python SDK, [`capawesome-cloud`](https://pypi.org/project/capawesome-cloud/){:target="_blank"}, gives you a fully typed, synchronous interface to the [Capawesome Cloud API](../api.md). Use it to manage apps, Live Update channels and deployments, native builds, app store destinations, and more from your own backend or tooling — anywhere the [CLI](../cli/index.md) isn't a fit.

!!! info "API in development"

    The Capawesome Cloud API is still evolving and may change without notice. Response types intentionally expose only the most relevant properties to keep breaking changes to a minimum.

## Installation

Install the package from PyPI. It requires **Python 3.9 or later**:

```bash
pip install capawesome-cloud
```

## Authentication

Create an [API token](../accounts/tokens.md) in the Console and pass it to the client, or set the `CAPAWESOME_CLOUD_TOKEN` environment variable (with `CAPAWESOME_TOKEN` accepted as a fallback):

```python
from capawesome_cloud import CapawesomeCloud

client = CapawesomeCloud(token="cap_...")
```

The client holds a connection pool, so reuse a single instance. Use it as a context manager — or call `client.close()` — to release connections when you're done:

```python
with CapawesomeCloud(token="cap_...") as client:
    for app in client.apps.list():
        print(app.id, app.name)
```

### Configuration

The client accepts a few options beyond the token:

| Option | Type | Default | Description |
| --- | --- | --- | --- |
| `token` | `str` | `CAPAWESOME_CLOUD_TOKEN` env var | API token used to authenticate. |
| `base_url` | `str` | `https://api.cloud.capawesome.io` | Base URL of the API. |
| `timeout` | `float` | `30.0` | Request timeout in seconds. |
| `max_retries` | `int` | `2` | Retries with exponential backoff. `429` is always retried; network/`5xx` failures are retried only for idempotent methods. |
| `http_client` | `httpx.Client` | `None` | Bring your own pre-configured `httpx.Client`. |

## Usage

Resources mirror the API's path hierarchy: app-scoped resources are nested under `client.apps.*` and take `app_id` as their first argument, while top-level resources such as `client.jobs` sit directly on the client.

### Trigger a build and wait for it

A native build runs as a background **job**. Trigger it, then use the `wait()` helper to block until the job finishes:

```python
build = client.apps.builds.create(app_id, platform="ios", git_ref="main")

job = client.jobs.wait(build.job_id)
print(job.status)
```

### Promote a build to a channel

Create a deployment to publish a build to a Live Update channel — optionally as a gradual rollout:

```python
deployment = client.apps.deployments.create(
    app_id,
    app_build_id=app_build_id,
    app_channel_name="production",
    rollout_percentage=0.5,
)
```

### Pagination

List methods return an iterator that lazily pages through **all** results. Iterate it directly, or collect everything with `to_list()`:

```python
for device in client.apps.devices.list(app_id):
    print(device.id, device.app_version_name)

channels = client.apps.channels.list(app_id).to_list()
```

To fetch a single page with manual offset control, use `list_page()`:

```python
page = client.apps.channels.list_page(app_id, limit=20, offset=0)
```

## Responses

Responses are typed [Pydantic](https://docs.pydantic.dev){:target="_blank"} models, with app-scoped models prefixed `App` (`AppChannel`, `AppBuild`, …) to match the API's entity names. Only the most relevant fields are part of the public contract; any extra fields the API returns are still accessible via `model_dump()` but shouldn't be relied upon:

```python
channel = client.apps.channels.get(app_id, channel_id)
print(channel.name, channel.created_at)   # documented fields
print(channel.model_dump())               # full raw payload
```

## Reference

The SDK covers the full API surface — apps, channels, deployments, builds and artifacts, certificates, environments, automations, devices, webhooks, and jobs. For the complete list of resources and options, see the [package on PyPI](https://pypi.org/project/capawesome-cloud/){:target="_blank"} and the [source on GitHub](https://github.com/capawesome-team/cloud-python){:target="_blank"}, or browse the underlying [Cloud API](../api.md).