Skip to main content
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.
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. 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 prompts and project_environments. See Prompt management.
  • 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.