Skip to main content
The to11 Python SDK gives Python services typed access to the to11 platform API. The distribution is published as to11ai-sdk and imported as to11ai_sdk. The current version is 0.2.0 and the package is licensed under MPL-2.0. Its only runtime dependency is Pydantic (>=2.13).
This SDK talks to the to11 platform API, the control plane, to manage prompts and routing rules. It is not the path for sending LLM or chat traffic. To send model requests, point a provider SDK such as OpenAI or Anthropic at the gateway base URL https://gw.to11.ai/v1. See Integrations. For that reason the SDK has no .chat() method.

​
Installation

The SDK requires Python 3.10 or later, and to11ai-sdk 0.2.0 or later. Install it with the package manager of your choice. 
pip install to11ai-sdk
The client is synchronous. There is no asynchronous client; all methods return values directly.

​
Authentication

The SDK authenticates with a to11 API key, sent as a standard Authorization: Bearer <to11-api-key> HTTP header. The client sets this header from the api_key value passed at construction. The project is identified in the URL path of each request, not in a header. Read the key from an environment variable rather than embedding it in source: 
import os

api_key = os.environ["TO11_API_KEY"]

​
Creating a client

Construct a client with the create_client factory. All arguments are keyword-only. 
import os
from to11ai_sdk import create_client

client = create_client(
    api_key=os.environ["TO11_API_KEY"],
    base_url="https://api.to11.ai",
)
project_id is not a constructor argument. It is passed on every resource method call. This differs from the to11 TypeScript SDK, where the project is configured once on the client.

​
Options

ArgumentTypeDefaultDescription
api_keystrrequiredThe to11 API key. Must be non-empty.
base_urlstrrequiredThe platform API base URL. Use https://api.to11.ai.
timeout_sfloat30.0Per-request timeout, in seconds.
max_retriesint3Maximum number of retry attempts per request.
ttl_secondsint300Time-to-live for cached responses, in seconds.
max_cache_entriesint100Maximum number of entries held in the response cache.
behavior_overridesMapping | NoneNoneOptional client behavior overrides.

​
Resolving prompts

client.prompts.resolve returns the resolved content of a prompt for a project, selected by slug and label. It is the prompt-resolution method in the Python SDK. 
prompt = client.prompts.resolve(
    project_id="proj_abc123",
    slug="welcome-message",
    labels=["production"],
)
print(prompt.messages)
The prompts namespace also provides:
  • Prompt lifecycle methods: create, list, get, update, and archive.
  • Version methods: create_version, list_versions, get_version, move_label, and list_labels.
  • Project-label methods: list_project_labels, create_project_label, get_project_label, update_project_label, delete_project_label, list_project_label_usages, and list_label_events.
All methods take keyword-only arguments.

​
Managing routing rules

The client.routing_rules namespace manages routing rules through two nested namespaces. client.routing_rules.versions manages rule versions:
  • create creates a new rule version.
  • list lists rule versions.
  • get retrieves a single rule version.
client.routing_rules.releases manages which version is released to an environment:
  • set releases a version.
  • rollback reverts to a previous release.
  • list lists releases.

​
Project environments

The client.project_environments namespace manages a project’s environments. It provides list, get, create, update, archive, and restore.

​
Error handling

The SDK raises typed exceptions. To11aiError is the base class; all other SDK errors inherit from it. Catch To11aiError to handle any SDK error, or catch a specific subclass.
ExceptionRaised when
To11aiErrorBase class for all SDK errors.
To11aiApiErrorThe API returns an error response. Carries status_code, error_code, and details.
To11aiAuthErrorThe request is unauthorized or forbidden (HTTP 401 or 403).
To11aiRateLimitErrorThe request is rate limited (HTTP 429). Carries retry_after_seconds.
To11aiValidationErrorThe request is rejected as invalid (HTTP 400).
To11aiNetworkErrorA network-level failure prevents the request from completing.
RuleNotFoundErrorThe referenced routing rule does not exist.
NoApplicableRouteErrorNo routing rule applies to the request.
EnvNotEnabledForProviderErrorThe environment is not enabled for the provider.
RuleVersionInvalidSnapshotErrorThe rule version references an invalid snapshot.
PromptLabelNotRegisteredErrorThe referenced prompt label is not registered.
The Python SDK exposes a smaller set of named exceptions than the TypeScript SDK. Some prompt- and environment-specific conditions that the TypeScript SDK raises as dedicated classes (for example PromptNotFoundError or EnvNotFoundError) surface in Python as a To11aiApiError — inspect its error_code and status_code to distinguish them.
from to11ai_sdk import To11aiAuthError

try:
    prompt = client.prompts.resolve(
        project_id="proj_abc123",
        slug="welcome-message",
        labels=["production"],
    )
except To11aiAuthError:
    print("Check that TO11_API_KEY is set and valid.")

​
Next steps

TypeScript SDK

The to11 TypeScript SDK.

API reference

The underlying HTTP API.