> ## 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 managed prompt, shape it per provider, or convert the neutral result.

`client.prompts.render(slug, options?)` renders a prompt's `latest` version for the client's `projectId` in a single request. Set `format` — on the client or per call — to get a result shaped for that provider; omit it to get the neutral result.

```ts theme={null}
const to11 = createClient({ format: "openai" });

const prompt = await to11.prompts.render("welcome-message", {
  variables: { name: "Ada" },
});
```

The options object is `{ format?, label?, variables?, fallback?, onUnknownRole? }`: `label` names the label to render — `latest`, the only label a prompt has, which is also what an omitted `label` serves — `format` overrides the client default, and `fallback` is served on a network error or a 5xx from the control plane, never on a 4xx. The return shape is fixed by the call's `format`, not by the network outcome. Authored `developer` blocks render as-is; the SDK maps them per provider (OpenAI keeps `developer`, Anthropic folds them into `system`). `onUnknownRole` (`"drop"` default, `"warn"`, or `"error"`) sets how a message with an unrecognized role is handled during provider conversion — see [Unknown roles](#unknown-roles).

## Shaped result

With a `format`, `render` returns a result you can spread straight into a provider request. `format: "openai"` returns `{ messages, config, metadata }`; `format: "anthropic"` returns `{ system, messages, config, metadata }` — the authored system and developer instructions are folded into a top-level `system` string, which Anthropic takes as a separate request field. When the prompt authors tools, the result also carries provider-shaped `tools` and `tool_choice`.

| Field | Holds |
| - | - |
| `system` | **Anthropic only.** The folded system/developer instruction text, passed as Anthropic's top-level `system`. Omit it and you drop the authored instructions. |
| `messages` | The rendered messages, shaped for the provider. |
| `config` | Model parameters from the resolved version — `model`, `temperature`, `max_tokens`, and any other stored keys — passed through verbatim. |
| `tools` / `tool_choice` | Provider-shaped tool definitions and directive, present only when the prompt authors tools. Spread them into the request so a tool-using prompt isn't sent without its tools. |
| `metadata` | Provenance: `promptId`, `version`, `versionId`, `label` (the label the prompt resolved through, `latest`), and `slug`. |

Spread the result into the request:

```ts theme={null}
// OpenAI — `tools`/`tool_choice` are undefined (and omitted) unless the prompt authors tools
const res = await openai.chat.completions.create({
  ...prompt.config,
  messages: prompt.messages,
  tools: prompt.tools,
  tool_choice: prompt.tool_choice,
});
```

```ts theme={null}
// Anthropic — pass the folded `system` and the shaped tools alongside the messages
const res = await anthropic.messages.create({
  ...prompt.config,
  system: prompt.system,
  messages: prompt.messages,
  tools: prompt.tools,
  tool_choice: prompt.tool_choice,
});
```

## Neutral result and converters

Omit `format` (on both the client and the call) to get the neutral `RenderedPrompt`: `messages`, `tools`, `toolChoice`, `promptId`, `version`, `versionId`, `contentHash`, `label`, `slug`, `blockRenderRecord`, and `modelConfig`. This is the path for providers the shaper does not cover (Vercel AI, LangChain) or for driving one prompt through more than one provider.

The package root, `@to11ai/sdk`, exports the converters that turn a neutral result into a provider's request shape:

| Helper | Purpose |
| - | - |
| `toOpenAIMessages` / `toAnthropicMessages` | Convert the neutral `messages` to the provider's message list. Both accept an `{ onUnknownRole }` option — see [Unknown roles](#unknown-roles). |
| `toAnthropicSystem` | Fold the `system`/`developer` turns into Anthropic's top-level `system` string (they are omitted from `toAnthropicMessages`). Pair the two for an Anthropic call. |
| `toOpenAITools` / `toAnthropicTools` | Convert `tools` to the provider's tool schema. |
| `toOpenAIToolChoice` / `toAnthropicToolChoice` | Convert `toolChoice` to the provider's directive. |

With a `format`, `render` applies the conversion for you, so most apps call the converters only for message history they build themselves, such as a rendered prompt followed by the conversation so far:

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

const to11 = createClient(); // no format: render returns the neutral result
const rendered = await to11.prompts.render("weather-concierge", {
  variables: { city: "New York" },
});
const system = toAnthropicSystem(rendered.messages);
const messages = toAnthropicMessages([...rendered.messages, ...history]);
```

`history` here is your own conversation in the same neutral shape, `RenderedChatMessage[]`.

## Unknown roles

The message converters recognize `system`, `user`, `assistant`, `developer`, and `tool`. A message whose role is anything else is handled by the `onUnknownRole` policy — set it per call, on `createClient`, or on the converter directly:

| Mode | Behavior |
| - | - |
| `"drop"` (default) | The message is omitted silently. |
| `"warn"` | The message is omitted and a `console.warn` names the role and index. |
| `"error"` | Conversion throws `UnknownRoleError` (carrying `code: "unknown_role"`, `role`, and `index`). |

```ts theme={null}
// Fail loudly when a hand-built message array has an unrecognized role
const messages = toOpenAIMessages(history, { onUnknownRole: "error" });
```

A prompt rendered by to11 only ever carries known roles, so on `render()` this matters mainly when you convert your own message arrays (assembled conversation history, messages from another source). `onUnknownRole: "error"` on `render()` is a way to assert that invariant explicitly.

## Skills

A [skill](https://to11.ai/docs/skills/concepts.md) is the second kind of prompt: it is delivered to a developer's machine as files and read there by a coding agent, rather than sent to a model as messages. `render()` does not render one.

* **You will not find one by accident.** `prompts.list()` returns chat prompts only.
* **If you render one with `render()`, it throws.** The SDK validates every render response against a closed schema, and a skill's response does not match it, so the call raises a validation error rather than handing back something your code would misread.
* **To read a skill's files from code**, list the skills across an organization with `prompts.listOrgPrompts({ orgId })` and render one exact version with `prompts.renderSkillVersion({ projectId, slug, version })`. The result's `files` holds each file's `filename` and `content`. See [Prompt management](https://to11.ai/docs/reference/typescript-sdk/prompts.md#skills).

To install skills on a machine, use the [to11 CLI](https://to11.ai/docs/reference/cli.md).


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