Docs/Llmops/Prompts Api

Prompts API & Caching

The SDKs fetch prompts through the public REST API. You can call the same endpoints directly, for example from a language without an SDK or from a deployment script.

Authentication

Use HTTP Basic auth with a project public key as the username and its secret key as the password. Organization keys are rejected for prompt endpoints. See Authentication.

bash

curl -u "pk-ap-...:sk-ap-..." \ "https://<your-host>/api/public/v2/prompts/support%2Fanswer?label=production"

URL-encode the prompt name. A name with a folder such as support/answer becomes support%2Fanswer.

Endpoints

Paths are relative to https://<your-host>/api/public.

Method and path	What it does
`GET /v2/prompts/{promptName}`	Get one prompt version. Pass `version=<n>` or `label=<label>`, not both. With neither, the version labelled `production` is returned.
`GET /v2/prompts`	List prompts. Filters: `name`, `label`, `tag`, `fromUpdatedAt`, `toUpdatedAt`. Paging: `page` (from 1) and `limit` (default 10, at most 100).
`POST /v2/prompts`	Create a new version of a prompt. Creates the prompt if the name is new.
`PATCH /v2/prompts/{promptName}/versions/{version}`	Add labels to a version with `{"newLabels": ["production"]}`. The version keeps its existing labels, and each added label is removed from the version that had it.

Get a prompt

The response is one prompt version:

json

{ "name": "support/answer", "version": 3, "type": "chat", "prompt": [ { "role": "system", "content": "You are a support agent for {{product}}." }, { "role": "user", "content": "{{question}}" } ], "config": { "model": "gpt-4o-mini", "temperature": 0.2 }, "labels": ["production", "latest"], "tags": ["support"], "commitMessage": "Shorter system message" }

If the prompt references other prompts, the response contains the resolved text and a resolutionGraph describing the references. A missing prompt, version or label returns 404.

List prompts

Each list entry has name, versions, labels, tags, lastUpdatedAt and lastConfig, with paging under meta:

json

{ "data": [ { "name": "support/answer", "versions": [1, 2, 3], "labels": ["latest", "production"], "tags": ["support"], "lastUpdatedAt": "2026-10-01T09:30:00.000Z", "lastConfig": { "model": "gpt-4o-mini" } } ], "meta": { "page": 1, "limit": 10, "totalItems": 1, "totalPages": 1 } }

Create a version

bash

curl -u "pk-ap-...:sk-ap-..." \ -X POST "https://<your-host>/api/public/v2/prompts" \ -H "Content-Type: application/json" \ -d '{ "name": "support/answer", "type": "text", "prompt": "Answer the question about {{product}}: {{question}}", "labels": ["staging"], "config": { "model": "gpt-4o-mini" }, "tags": ["support"], "commitMessage": "Plain text variant" }'

Field	Notes
`name`	Required.
`type`	`text` or `chat`. Defaults to `text`.
`prompt`	A string for `text`. For `chat`, a list of `{"role", "content"}` messages, and optionally placeholder messages `{"type": "placeholder", "name": "history"}`.
`labels`	Optional. Lowercase letters, digits, `_`, `-` and `.`, up to 36 characters. `latest` is set automatically.
`config`	Optional JSON object.
`tags`	Optional. Tags apply to all versions of the prompt.
`commitMessage`	Optional note for this version.

Change labels

bash

curl -u "pk-ap-...:sk-ap-..." \ -X PATCH "https://<your-host>/api/public/v2/prompts/support%2Fanswer/versions/3" \ -H "Content-Type: application/json" \ -d '{ "newLabels": ["production"] }'

You cannot set latest. It always points at the newest version.

ℹ

Some self-hosted deployments limit project API keys to sending trace data. On those deployments GET requests for prompts still work, but creating and relabelling prompts with an API key returns 403.

Rate limits

Prompt endpoints have their own rate limit bucket. A limited request returns 429 with a Retry-After header. See API Reference.

Caching

Two caches sit between a prompt change and your application.

Server cache

ANTS Platform caches fetched prompts in Redis so repeated fetches do not hit the database. Entries live for 300 seconds by default.

When a new version is created or labels change, the platform clears the cached entries for that prompt name. The next fetch reads the database and returns the new version, so a label move takes effect on the server right away.

On self-hosted deployments the cache is on by default when Redis is configured. LANGFUSE_CACHE_PROMPT_ENABLED turns it on or off and LANGFUSE_CACHE_PROMPT_TTL_SECONDS sets the lifetime.

SDK cache

The Python SDK keeps fetched prompts in memory:

The default lifetime is 60 seconds. Change it per call with cache_ttl_seconds=, or for the whole process with the ANTS_PLATFORM_PROMPT_CACHE_DEFAULT_TTL_SECONDS environment variable.
After the lifetime ends, get_prompt returns the cached version immediately and refreshes it in the background. Your application sees a label change within about one cache lifetime.
cache_ttl_seconds=0 fetches from the server on every call.
If a fetch fails and an older copy is cached, the SDK returns the older copy. With nothing cached, it returns the fallback= you pass, or raises.
clear_prompt_cache() empties the cache.

python

from ants_platform import get_client ants = get_client() prompt = ants.get_prompt( "support/answer", label="production", type="chat", cache_ttl_seconds=300, fallback=[{"role": "user", "content": "{{question}}"}], )

Next steps

Prompt Management
API Reference
Automations: get a webhook or Slack message when a prompt version changes.