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.
{ 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 aformat, 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
Omitformat (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 recognizesystem, 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:
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 withprompts.renderSkillVersion({ projectId, slug, version }). The result’sfilesholds each file’sfilenameandcontent. See Prompt management.