> ## 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.

# Rendering Prompts

> Render a prompt's newest version from your application at runtime, fill its variables, and send its messages and tools to the model.

Because `render` serves a prompt's `latest` version, the prompt your application serves changes the moment you publish a new version in the dashboard, with no redeploy. The next request renders it.

The examples show both the [TypeScript](https://to11.ai/docs/reference/typescript-sdk.md) SDK (`@to11ai/sdk`) and the [Python](https://to11.ai/docs/reference/python-sdk.md) SDK (`to11ai-sdk`), which expose the same `prompts` surface (TypeScript in camelCase, Python in snake\_case).

## Create the client

The SDK's `prompts.*` methods talk to the to11 API. Create one client with your API key and the project id, so `render` can default to them:

```ts TypeScript theme={null}
import { createClient } from "@to11ai/sdk";

const to11 = createClient({
  apiKey: process.env.TO11_API_KEY,
  projectId: process.env.TO11_PROJECT_ID,
});
```

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

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

Both SDKs read `TO11_API_KEY` and `TO11_PROJECT_ID` from the environment when you leave the options out, and `TO11_API_URL` for the API address, which defaults to `https://api.to11.ai`. The key needs the `prompt:read` scope; see [API keys](https://to11.ai/docs/platform/api-keys.md).

`render` serves `latest`, the one label a prompt has, which always points at the version you published last. Every call also takes a `label` option; `latest` is the only value it accepts today.

## Render a prompt

Call `prompts.render` with the prompt's slug and the [variables](https://to11.ai/docs/platform/prompts/authoring.md#variables) it needs:

```ts TypeScript theme={null}
const rendered = await to11.prompts.render("weather-concierge", {
  variables: {
    assistant_name: "Roker",
    city: "New York",
    units: "fahrenheit",
    user_message: "Do I need a jacket?",
    tier: "vip",   // a non-renderable variable: drives conditions, never rendered
  },
});
```

```python Python theme={null}
rendered = to11.prompts.render(
    "weather-concierge",
    variables={
        "assistant_name": "Roker",
        "city": "New York",
        "units": "fahrenheit",
        "user_message": "Do I need a jacket?",
        "tier": "vip",   # a non-renderable variable: drives conditions, never rendered
    },
)
```

You pass every value the prompt needs in one `variables` object. A value fills the `{{ placeholders }}` it's referenced in and can also drive [conditions](https://to11.ai/docs/platform/prompts/authoring.md#conditions); a value the prompt marks [non-renderable](https://to11.ai/docs/platform/prompts/authoring.md#renderable-variables) (like `tier` here) drives conditions but is never rendered. See [Variables](https://to11.ai/docs/platform/prompts/authoring.md#variables).

The result carries everything needed to call the model:

| Field | What it holds |
| - | - |
| `rendered.messages` | The rendered messages, with variables substituted and non-matching conditional blocks dropped. |
| `rendered.tools` | The [tool definitions](https://to11.ai/docs/platform/prompts/authoring.md#tool-definitions) for this version, in a provider-neutral shape. |
| `rendered.toolChoice` | The tool-choice directive (`auto`, `none`, `required`, or a specific tool). |
| `rendered.modelConfig` | The version's model settings from the **Config** pane. See [Model configuration](#model-configuration). |
| `rendered.promptId` / `rendered.version` | Which prompt and version resolved, for your own logging. |

In Python the same fields use snake\_case: `rendered.tool_choice`, `rendered.prompt_id`, and `rendered.model_config_`.

### The developer role

Blocks carry a [role](https://to11.ai/docs/platform/prompts/overview.md#message-roles), and the author's roles outrank the end user's. The **`developer`** role is OpenAI's name for that application-author layer. OpenAI describes a developer message as "instructions provided by the application developer, prioritized ahead of user messages," and offers an analogy: a developer message is like a function definition that sets the rules and business logic, while a user message supplies the arguments those rules run against. Historically this layer was the `system` role, and many models still use that name; OpenAI's newer models accept `developer` as a distinct role. See OpenAI's [text generation guide](https://developers.openai.com/api/docs/guides/text) for the details.

A resolved prompt returns your authored roles **as-is** — a `developer` block comes back as a `developer` message. Converting that to what each provider expects is the SDK's job:

* **OpenAI** accepts `developer` (its modern name for the author layer), so it is passed through unchanged.
* **Anthropic** has no `developer` role, so it goes in Anthropic's top-level `system` field: `toAnthropicSystem` (`to_anthropic_system` in Python) folds the `system` and `developer` turns into that string, and `toAnthropicMessages` omits them from the message list.

So you don't pick a role mapping — you author `developer` blocks, and the SDK places them correctly for the provider you call.

## Model configuration

The model id and generation settings (temperature, token limit) are authored on the version in the editor's **Config** pane, separate from the rendered messages. A render returns them with the messages: as `rendered.modelConfig` on the neutral result (`rendered.model_config_` in Python, with a trailing underscore), and as `config` when you set a `format`, ready to spread into the provider request.

```ts TypeScript theme={null}
const cfg = rendered.modelConfig ?? {}; // { model, temperature, max_tokens }
```

```python Python theme={null}
cfg = rendered.model_config_ or {}   # {"model", "temperature", "max_tokens"}
```

To read the settings of any other version, call `getVersion` (`get_version` in Python) with the prompt id and version number.

> [!NOTE]
>
> Both SDKs default the project on every `prompts.*` method from the client — `createClient({ projectId })`, `create_client(project_id=...)` — so you omit it per call and pass it only to override.

## Send it to the model

Rendered messages, tools, and tool choice are provider-neutral. Set `format` and the SDK shapes them for your provider, together with the version's model settings, so you can pass the result straight to the provider client you already use, with your own provider key:

```ts TypeScript theme={null}
import OpenAI from "openai";

const prompt = await to11.prompts.render("weather-concierge", {
  format: "openai",
  variables, // the same values as in "Render a prompt"
});

const openai = new OpenAI(); // reads OPENAI_API_KEY
const completion = await openai.chat.completions.create({
  ...prompt.config,            // model, temperature, max_tokens from the Config pane
  messages: prompt.messages,
  tools: prompt.tools,         // present only when the prompt defines tools
  tool_choice: prompt.tool_choice,
});
```

```python Python theme={null}
from openai import OpenAI

prompt = to11.prompts.render(
    "weather-concierge",
    format="openai",
    variables=variables,  # the same values as in "Render a prompt"
)

openai = OpenAI()  # reads OPENAI_API_KEY
completion = openai.chat.completions.create(
    **prompt["config"],          # model, temperature, max_tokens from the Config pane
    messages=prompt["messages"],
    **({"tools": prompt["tools"]} if "tools" in prompt else {}),
    **({"tool_choice": prompt["tool_choice"]} if "tool_choice" in prompt else {}),
)
```

Every part of the request (messages, tools, tool choice, and model settings) now comes from the published prompt version; nothing is hardcoded. With `format: "anthropic"` the result also carries a top-level `system`, which you pass as Anthropic's `system` field. Set `format` once on the client instead of per call if every render goes to the same provider.

To convert a neutral result yourself, for example to append your own conversation history before sending, use the converters both SDKs export from their root: `toOpenAIMessages`, `toOpenAITools`, `toOpenAIToolChoice`, `toAnthropicMessages`, `toAnthropicSystem`, `toAnthropicTools`, and `toAnthropicToolChoice` in TypeScript, and the same names in snake\_case in Python. See the [TypeScript](https://to11.ai/docs/reference/typescript-sdk/rendering-prompts.md) and [Python](https://to11.ai/docs/reference/python-sdk/rendering-prompts.md) SDK references.

### Tools and tool choice

`rendered.tools` and `rendered.toolChoice` mirror the version's [Tools pane](https://to11.ai/docs/platform/prompts/authoring.md#tool-definitions). A specific tool-choice that names a tool no longer present in the resolved version is dropped rather than sent, so a stale directive can't force a call to a tool that isn't offered.

## Resolution and fallbacks

* **The `latest` label.** Once a prompt or skill has a version, it carries `latest`, the one label there is, which resolves to its newest version. A render with no `label` serves it, and `label: "latest"` is the same request. Only publishing a version moves it, and no environment can be named `latest`.
* **Any other label** answers `404` with the code `LABEL_NOT_FOUND`.
* **A prompt with no version** answers `409` with the code `PROMPT_HAS_NO_VERSIONS`.
* **Offline fallback.** If you pass a `fallback` and the request fails on a network error or a 5xx from the control plane, the SDK serves the fallback instead of throwing, so a control-plane blip degrades gracefully rather than taking your feature down. A 4xx — an unknown prompt or label, a prompt with no version — is never masked.

## Rendering a skill

Everything above renders a **chat prompt**, and the result is a set of messages you send to a model. Rendering a **[skill](https://to11.ai/docs/skills/concepts.md)** through the same endpoint returns something different: a **file set**, not a string and not messages.

```json theme={null}
{
  "promptId": "prompt_01M3K…",
  "versionId": "pv_01M3…",
  "version": 4,
  "label": "latest",
  "contentHash": "sha256:…",
  "format": "skill",
  "files": [
    { "id": "block_01M3K…", "filename": "SKILL.md", "contentType": "text/markdown", "content": "---\nname: incident-triage\n…" },
    { "id": "block_01M3L…", "filename": "references/core.md", "contentType": "text/markdown", "content": "…" }
  ]
}
```

A skill render carries no `rendered` field at all, because there is nothing to send to a model — the `format` tells the two answers apart. The entry document's frontmatter is **generated at render time** from the skill's slug, its description and the prefix you send, and the links between its files come back as filenames.

**Rendering one version.** A render through `latest` answers with the newest stored version, which is the right question for a machine that follows it. A machine pinned to a version is asking a different one — so `POST /v1/projects/:projectId/prompts/by-slug/:slug/versions/:versionNumber/render` renders a named version directly.

It takes the same target and returns the same files, minus `label` — no label is in play, and a field present and empty would invite you to read it. It is skills only: a chat prompt at that address is a `409`, the same as every other kind mismatch.

**The render target.** A skill has no variables, so that channel carries the target instead — `{ "variables": { "target": "claude-code" } }`. Today every target produces identical output, which is the form every coding agent accepts; the parameter is recorded now so adding per-agent dialects later changes a renderer rather than the contract. An unrecognized target is an error naming the ones that exist, never a silent fall back.

**The directory prefix.** The same channel carries the name of the directory you are about to write the file set into — `{ "variables": { "target": "claude-code", "prefix": "acme-" } }`. The Agent Skills standard requires the entry document's `name` to equal its parent directory, and only the caller knows what that directory is called, so `name` comes back as `<prefix><slug>`. Send nothing and it comes back as the bare slug, which is the right answer when you are writing into a directory named after the slug. Unlike the target, a prefix that cannot be read is not an error: it names the delivery, and the only caller it can mislead is the one that sent it.

> [!NOTE]
>
> **`render()` does not render a skill.** Both SDKs validate its response against a closed schema that admits the chat shape only, so a skill fails validation rather than being misread. A skill is delivered to a developer's machine by the to11 CLI. To read one exact version's files from code, both SDKs have `renderSkillVersion` (`render_skill_version` in Python), which calls the version-addressed route above.

## Errors

`render` throws typed errors you can branch on: a missing prompt, a label that doesn't exist, or a prompt with no version yet. See the [TypeScript SDK reference](https://to11.ai/docs/reference/typescript-sdk/errors.md) for the full list and their fields.

## Migration notes

Both SDKs expose only `render()`; the older label-addressed `resolve()` was removed in 2.0. A render with no `label` serves `latest`. The client's `env` option is gone. See the [TypeScript](https://to11.ai/docs/reference/typescript-sdk.md) and [Python](https://to11.ai/docs/reference/python-sdk.md) SDK references.

> [!NOTE]
>
> Earlier TypeScript SDK builds (0.8.x) accepted a separate `context` argument on `render`. It's been removed: pass those values in `variables` instead, turning off [renderable](https://to11.ai/docs/platform/prompts/authoring.md#renderable-variables) on the ones that shouldn't appear in the text. An old build still sending `context` is accepted without error, but the values are ignored, so blocks that gated on them stop gating until you migrate.

## Next steps

> [card] [Authoring prompts](https://to11.ai/docs/platform/prompts/authoring.md)
>
> Build the variables, tools, and config that shape what you render.

> [card] [TypeScript SDK](https://to11.ai/docs/reference/typescript-sdk.md)
>
> Full `prompts.*` method and error reference.

> [card] [Versions](https://to11.ai/docs/platform/prompts/versions.md)
>
> Publish immutable versions; `latest` follows the newest.

> [card] [Python SDK](https://to11.ai/docs/reference/python-sdk.md)
>
> The same `prompts` surface in Python.


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