Skip to main content
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.
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.

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. Spread the result into the request:

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: 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:
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:
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 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.
To install skills on a machine, use the to11 CLI.