> ## Documentation Index
> Fetch the complete documentation index at: https://docs.darwin.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK Specification

> Client architecture, configuration, resources, retries, and async behavior for the Darwin Python SDK.

The Darwin Python SDK is generated from the reviewed public OpenAPI contract. This page defines the client surface and runtime behavior; use the [API reference](/api-reference/introduction) for endpoint schemas.

## Clients

```python theme={null}
from darwin_sdk import AsyncDarwin, Darwin

client = Darwin(token="...")
async_client = AsyncDarwin(token="...")
```

`Darwin` is synchronous. `AsyncDarwin` exposes the same resource methods as coroutines. Create clients once and reuse them so their underlying HTTP sessions can reuse connections.

## Configuration

Both clients accept:

* `token` — a bearer token string or token provider
* `environment` or `base_url` — production by default, or an explicit API origin
* `timeout` — request timeout in seconds; the generated default is 60 seconds
* `max_retries` — retry ceiling; the generated default is 2
* `headers` — additional headers sent with every request
* `logging` — SDK logging configuration or a custom logger

`AsyncDarwin` also accepts `async_token` and a custom `httpx.AsyncClient`.

```python theme={null}
client = Darwin(
    token="...",
    timeout=20,
    max_retries=2,
    headers={"X-Request-Source": "worker"},
)
```

## Resource clients

| Property        | Purpose                                                                 |
| --------------- | ----------------------------------------------------------------------- |
| `account`       | Authenticated account and plan context                                  |
| `agents`        | Agents, skills, assets, teams, access, and integrations                 |
| `requests`      | Inbound requests and decisions                                          |
| `conversations` | Account-routed and agent-scoped messages                                |
| `goals`         | Outcomes, state changes, and publication requests                       |
| `deals`         | Commercial terms, decisions, and payments                               |
| `applications`  | Darwin Connect applications, enrollment, service accounts, and webhooks |

The public product name is **Connect**; `applications` remains the generated client property for compatibility with the current API contract.

## Naming and return types

Python methods use `snake_case` and return generated typed models.

```python theme={null}
response = client.agents.list_agents()
agent = response.agents[0]

skills = client.agents.list_agent_skills(agent_id=agent.id)
```

Method arguments are keyword arguments except identifiers that the generated signature marks as positional. Model fields use Python naming while request serialization follows the API schema.

## Async usage

```python theme={null}
from darwin_sdk import AsyncDarwin

client = AsyncDarwin(token="...")
turn = await client.conversations.create_message(
    content="Summarize the requests that need attention.",
)
```

Use one async client per application lifecycle. If you provide a custom async HTTP client, its connection limits, proxies, and TLS configuration apply to every resource.

## Failures and retries

The SDK raises generated errors for non-success responses and transport failures. Retries are limited to eligible transient failures; validation or authorization errors are returned immediately. Set a request-specific timeout or retry count only when an operation needs behavior different from the client default.

<Warning>
  Retries can repeat a request. Use stable idempotency behavior for create or action methods and do not retry authorization or validation failures blindly.
</Warning>

See [Errors](/errors) for the public error model and [Python and TS Cheat Sheets](/sdks/cheat-sheets) for common method mappings.