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

# Configuration

> create_client options, credential resolution, and what the client exposes.

`create_client(**options)` is a factory function that returns a client. All arguments are keyword-only; call it directly (it is not a class).

```python theme={null}
import os
from to11ai_sdk import create_client

client = create_client(
    api_key=os.environ["TO11_API_KEY"],
    project_id=os.environ["TO11_PROJECT_ID"],
)
```

## Credential resolution

Each option resolves with its own precedence, so an app can construct the client from the environment alone:

* `base_url` — option → `TO11_API_URL` → `https://api.to11.ai`.
* `api_key`, `project_id` — option → environment variable (no default).
* `format`, `on_unknown_role` — option only.

An environment variable that is empty or only whitespace counts as unset. An explicit blank `api_key` or `project_id` option raises `ValueError`.

Authenticate with `api_key`, a to11 [API key](https://to11.ai/docs/platform/api-keys.md). It is required: `create_client` raises `ValueError` without one. The SDK sends it as `Authorization: Bearer <api_key>` and carries the project in the URL path.

> [!NOTE]
>
> Keep credentials server-side. A to11 API key must never ship to an end user's device. Use the SDK from a server, CLI, or backend job.

## Options

| Argument | Type | Resolves from | Default |
| - | - | - | - |
| `api_key` | `str \| None` | option → `TO11_API_KEY` | — (required) |
| `base_url` | `str \| None` | option → `TO11_API_URL` | `https://api.to11.ai` |
| `project_id` | `str \| None` | option → `TO11_PROJECT_ID` | `None` (required by `prompts.render()`) |
| `format` | `"openai" \| "anthropic" \| None` | option | `None` (omit for the neutral render result) |
| `on_unknown_role` | `"drop" \| "warn" \| "error" \| None` | option | `"drop"` |
| `timeout_s` | `float` | option | `30.0` |
| `max_retries` | `int` | option | `3` |

`max_retries` applies to network failures, timeouts, and 5xx responses on idempotent requests (`GET`, `PUT`, `DELETE`, and the other methods RFC 9110 calls idempotent). `POST` and `PATCH` are never retried, so a call that creates something cannot run twice.

## What the client exposes

* Resource namespaces `prompts` and `project_environments`. See [Prompt management](https://to11.ai/docs/reference/python-sdk/prompts.md).
* Read-only attributes for the resolved config: `client.base_url`, `client.api_key`, and `client.project_id` (or `None` when unset). `api_key` is a secret: it is left out of the client's `repr`, and you should never log it.

The `project_id` set here is the default for **every** `prompts.*` method — `render()` and the lifecycle, version, and label calls (`get`, `list`, `get_version`, `list_labels`, …). Bind it once on the client and omit it per call; pass `project_id` on an individual call only to override. `render()` always uses the client's `project_id`. The `project_environments` methods take `project_id` on every call.

`format` set on the client is the default for every `render()`; a call's own `format` overrides it. See [Rendering prompts](https://to11.ai/docs/reference/python-sdk/rendering-prompts.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.