Rendering prompts

client.prompts.render(slug, options?) resolves a prompt for the client’s projectId and env 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.

const to11 = createClient({ env: "production", format: "openai" });

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

The options object is { format?, label?, subject?, variables?, fallback?, onUnknownRole? }: label picks the label to resolve for this call (defaulting to the client’s env — env is a label value), format overrides the client default, subject (a stable id) pins a weighted release to a variant, and fallback is served on a network error. 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.

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`, `releaseId`, `label` (the single label the prompt resolved through), and `variantName` when a weighted release served a variant.

Spread the result into the request, and pass the whole result to turn.headers(prompt) for the provenance headers:

// 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,
  },
  { headers: to11.turn().headers(prompt) },
);

// 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,
  },
  { headers: to11.turn().headers(prompt) },
);

Neutral result and converters

Omit format (on both the client and the call) to get the neutral RenderedPrompt: messages, tools, toolChoice, promptId, version, versionId, releaseId, variantName, 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 @to11ai/sdk/gateway subpath converts 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.
`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.
`gatewayAuthHeaders`	The `x-to11-*` headers that authenticate a gateway call.
`gatewayPromptHeaders`	Prompt provenance headers for a rendered prompt.

gatewayAuthHeaders and gatewayPromptHeaders are also re-exported from the main @to11ai/sdk entry. With a format, render applies the message conversion for you, so most apps never call the converters directly.

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`).

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

SDKs

Gateway

Rendering prompts

Shaped result

Neutral result and converters

Unknown roles

​Shaped result

​Neutral result and converters

​Unknown roles

Shaped result

Neutral result and converters

Unknown roles