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 SDK (@to11ai/sdk) and the Python SDK (to11ai-sdk), which expose the same prompts surface (TypeScript in camelCase, Python in snake_case).
Create the client
The SDK’sprompts.* methods talk to the to11 API. Create one client with your API key and the project id, so render can default to them:
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.
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
Callprompts.render with the prompt’s slug and the variables it needs:
variables object. A value fills the {{ placeholders }} it’s referenced in and can also drive conditions; a value the prompt marks non-renderable (like tier here) drives conditions but is never rendered. See Variables.
The result carries everything needed to call the model:
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, and the author’s roles outrank the end user’s. Thedeveloper 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 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
developerrole, so it goes in Anthropic’s top-levelsystemfield:toAnthropicSystem(to_anthropic_systemin Python) folds thesystemanddeveloperturns into that string, andtoAnthropicMessagesomits them from the message list.
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: asrendered.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.
getVersion (get_version in Python) with the prompt id and version number.
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. Setformat 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:
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 and Python SDK references.
Tools and tool choice
rendered.tools and rendered.toolChoice mirror the version’s Tools pane. 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
latestlabel. Once a prompt or skill has a version, it carrieslatest, the one label there is, which resolves to its newest version. A render with nolabelserves it, andlabel: "latest"is the same request. Only publishing a version moves it, and no environment can be namedlatest. - Any other label answers
404with the codeLABEL_NOT_FOUND. - A prompt with no version answers
409with the codePROMPT_HAS_NO_VERSIONS. - Offline fallback. If you pass a
fallbackand 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 through the same endpoint returns something different: a file set, not a string and not messages.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.
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 for the full list and their fields.
Migration notes
Both SDKs expose onlyrender(); 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 and Python SDK references.
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 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
Authoring prompts
Build the variables, tools, and config that shape what you render.
TypeScript SDK
Full
prompts.* method and error reference.Versions
Publish immutable versions;
latest follows the newest.Python SDK
The same
prompts surface in Python.