Docs / Prompt API

// MANAGED, VERSIONED, GOVERNED PROMPTS

Prompt API

Store prompts as versioned templates in the registry, then either compile them (Render) or compile-and-dispatch them (Completions). The difference matters: only Completions produces a verifiable receipt, because only Completions actually called a model.

Render vs. Completions

Two endpoints, one template. They look similar and do very different things.

POST/v1/prompts/:id/renderCompile only

Compiles the named template version with your variables and returns the resolved messages. No model is called, so there is no receipt. Use it to preview, to lint, or to feed the messages into your own pipeline.

POST/v1/prompts/:id/completionsReceipted

Renders the template and dispatches it through the gateway — routing, guardrails, budget, and a billable=true receipt. The receipt's inputs_hash covers the fully-rendered messages, so the exact prompt that ran is provable without storing its text.

Why split them. Rendering is a pure function — cheap, side-effect-free, repeatable. Dispatching costs money and touches a provider. Keeping them separate means a "render" can never quietly bill you, and a "completion" always leaves a receipt. The boundary is auditable on purpose.

Templates, variables & partials

Templates use a simple {{ variable }} syntax with reusable {{> partial }} includes. Variables are typed; a missing required variable fails the render rather than silently producing an empty string.

render request
curl https://agentics.you/api/v1/prompts/support-reply/completions \ -H "Authorization: Bearer ak_…" \ -d '{ "version": "label:production", "variables": { "ticket": "#4821", "tone": "concise" }, "model": "@anthropic/claude-opus-4-8" }' # response carries x-agentics-receipt: <receipt_hash> — verify it.

Versions & labels

Every saved edit is an immutable version. You dispatch against a version two ways:

FieldTypeMeaning
idstringStable prompt identifier.
versionstringvN (pinned) or label:<name> (moving pointer).
prompt_version_idhexRecorded on the receipt — the exact version that produced the dispatch.
labelsstring[]e.g. production, staging. Repointing a label is an audited event.
Label moves are audited. Promoting a new version to production writes an audit-log entry — who, when, from which version to which. Combined with the per-receipt prompt_version_id, you can prove which prompt text was live for any past request.
Verify a receipt Config object