Retrieve a prompt in your application
Load a published configuration, assemble inputs, and call your provider.
Prompt retrieval returns saved messages and generation settings. It does not execute a model. Your application authenticates with a prompt-scoped retrieval key, selects a version, builds the input messages, and makes its own provider call.
Get the connection details
Complete the prompt's baseline and have an administrator create a retrieval key. Copy the prompt ID from the dashboard. Retrieve saved prompts from https://www.promptlens.io/api/v1/prompts/{promptId} using a retrieval key.
Set these values in your server environment:
export PROMPTLENS_RETRIEVAL_URL='https://www.promptlens.io'
export PROMPTLENS_PROMPT_ID='YOUR_PROMPT_ID'
export PROMPTLENS_RETRIEVAL_KEY='YOUR_RETRIEVAL_KEY'Screenshot placeholder — Retrieval connection details Show the prompt ID, public retrieval endpoint, label/version selector, and key-management controls with the secret concealed.
Select a saved version
curl --fail-with-body --silent --show-error \
"$PROMPTLENS_RETRIEVAL_URL/api/v1/prompts/$PROMPTLENS_PROMPT_ID" \
-H "Authorization: Bearer $PROMPTLENS_RETRIEVAL_KEY"| Selector | Behavior |
|---|---|
| No query parameter | Resolve production |
?label=staging | Resolve staging |
?version=1 | Retrieve immutable version 1 |
Supply either a label or a positive integer version, never both. Empty, duplicate, and unknown query parameters are rejected. A missing or unassigned label does not fall back to another version. See retrieve_prompt for the response fields and status codes.
Assemble and execute
For user_message, append the raw input as the final user message. For variables, substitute the input object's values into the saved placeholders. Retrieval itself leaves placeholders unresolved.
The TypeScript and Python examples execute the ticket router with User message input and an OpenRouter route. They use a separate provider credential: a PromptLens retrieval key cannot authorize an OpenRouter call, and application calls do not spend your organization's PromptLens Credits.
Cache and revalidate
Successful responses include an ETag, Cache-Control: private, no-cache, and Vary: Authorization. Keep a cached body with its ETag and revalidate using If-None-Match. A 304 has no body; reuse the body you already hold only after that successful revalidation. Authentication occurs before cache validation.
Key caches by prompt, selector, and authorization context. Revalidate label-based retrieval so publishing and rollback become visible. Decide explicitly how your application handles retrieval outages; do not silently treat an authorization failure or unassigned label as permission to serve another version.