create_client(**options) is a factory function that returns a client. All arguments are keyword-only; call it directly (it is not a class).
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.
api_key or project_id option raises ValueError.
Authenticate with api_key, a to11 API key. 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.
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
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
promptsandproject_environments. See Prompt management. - Read-only attributes for the resolved config:
client.base_url,client.api_key, andclient.project_id(orNonewhen unset).api_keyis a secret: it is left out of the client’srepr, and you should never log it.
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.