What it does
A prompt family holds versions that are appended and never edited. Each version is byte-immutable, links to its parent, carries a content hash, declares its input variables and refers to a model configuration by name. A movable pointer such as production names the live version, and a rollback appends a new version copied from an earlier one.
How it works
POST /v1/prompts creates a family with a stable id of letters, digits, underscore and hyphen. POST /v1/prompts/{family}/versions appends the next version; the server assigns the number, the parent link and the content hash, and ignores any client-supplied values for them. A version holds the prompt content, a list of declared variables (name, a type of string, number, boolean or json, a required flag and a description), a model configuration reference and an optional changelog note. The write is a compare-and-swap on the next slot, so two administrators racing for the same number cannot both win: one commits and the other retries against the new latest.
A version has a lifecycle state fixed at append time: draft (the default), published or archived, with legal moves checked against the current latest (a first version may be draft or published, and an archived version can be revived). Changing the state is therefore a new version, and the chain is the full audit history of both content and lifecycle. Rollback appends a published version whose content is copied byte for byte from an earlier one and records which version it restored.
Deployment pointers (for example current or production) are the one thing that moves. PUT /v1/prompts/{family}/pointers/{name} repoints a name; moving it never mutates a version. A model configuration is stored by reference (provider, model, tuning parameters and an optional config name that resolves elsewhere), and the validator rejects parameter keys that look like secret material at any depth.
Everything is stored under project-prefixed kinds. Creating, appending, rolling back and moving pointers need an admin or service credential; reads need any authenticated project credential. The evaluation harness pins a prompt by family, version and content hash.
Where you reach it
- HTTP
POST and GET /v1/prompts; POST and GET /v1/prompts/{family}/versions; POST /v1/prompts/{family}/rollback; GET and PUT /v1/prompts/{family}/pointers/{name}
Example
{
"family_id": "support-answer",
"content": "Answer the customer question from the context provided.",
"variables": [
{ "name": "question", "type": "string", "required": true },
{ "name": "context", "type": "string", "required": true }
],
"model_config": { "provider": "anthropic", "model": "your-model-id", "params": { "temperature": 0.2 } },
"state": "published",
"note": "first release"
}Limits
- Prompts are stored and versioned. Agents and the completion route do not resolve pointers; your application fetches the live version and sends it.
- The secret-key guard checks parameter key names, not values. A secret typed into a free-text value or into the prompt content is not detected.
- There is no templating engine. Declared variables are a contract your application honours; the platform does not render them.
- Read routes accept any authenticated project credential, so treat prompt text as readable by every holder of a project key.
Evidence
- On this siteHTTP API reference
- Tests17 store tests and 2 route tests cover immutability, concurrent append, lifecycle transitions, rollback, pointers and secret-key rejection at depth
Test coverage is listed as present in the engine repository at this edition. This page does not report test results.
KynetraDB is in private preview
Request a preview to try this against your own workload.