Retrieving prompts
Retrieve active, latest, or pinned managed prompt versions.
nirmos.prompts.retrieve accepts a prompt ID or slug. It returns the active version by default.
const prompt = await nirmos.prompts.retrieve("support-reply");
console.log(prompt.version.number);
console.log(prompt.content);Convenience methods make intent explicit:
const active = await nirmos.prompts.retrieveActive("support-reply");
const latest = await nirmos.prompts.retrieveLatest("support-reply");The latest version may still be a draft. Use the active version for normal production traffic.
Pin a version
const prompt = await nirmos.prompts.retrieve("support-reply", {
version: 7,
});Pin versions for evaluations, audits, replay jobs, and workflows that require reproducible behavior.
Render without a gateway request
const prompt = await nirmos.prompts.retrieve("support-reply");
const rendered = await nirmos.prompts.render(prompt, {
customerName: "Asha",
tone: "calm",
});
console.log(rendered.messages);
console.log(rendered.promptVersion);You can also render from a reference in one call:
const rendered = await nirmos.prompts.render(
{ id: "support-reply", version: "active" },
{ customerName: "Asha", tone: "calm" },
);Rendering happens locally. Values are substituted into text blocks and image URLs. Required variables and unresolved placeholders raise PromptRenderError.
To intentionally preserve unresolved placeholders:
const rendered = await nirmos.prompts.render(
prompt,
{ customerName: "Asha" },
{ allowUnresolved: true },
);Use this only for multi-stage templating. Normal production calls should fail before sending incomplete instructions.
Use directly in chat
const completion = await nirmos.gateway.chat.create({
model: "anthropic/claude-sonnet-4",
prompt: {
id: "support-reply",
version: "active",
variables: {
customerName: "Asha",
tone: "calm",
},
},
messages: [{ role: "user", content: ticket.body }],
});Prompt messages are inserted before request messages. Set position: "after" only when the prompt is intentionally a suffix.