Prompts API

Prompts

Save reusable prompts and use them by id in POST /v1/responses with prompt: {"id": "pmpt_...", "version": "2", "variables": {...}} (leave out version for the latest). A prompt holds instructions, input messages and default settings (model, tools, tool_choice, text, reasoning, temperature, top_p, max_output_tokens, parallel_tool_calls, truncation); fields you send with the request win. Its instructions come first, its messages before your input.

Prompts belong to your account: every key on it can use them.

Endpoints

• List prompts: GET https://api.openscale.so/v1/prompts
• Create a prompt: POST https://api.openscale.so/v1/prompts
• Retrieve a prompt: GET https://api.openscale.so/v1/prompts/{prompt_id}
• Save a new version: POST https://api.openscale.so/v1/prompts/{prompt_id}
• Delete a prompt: DELETE https://api.openscale.so/v1/prompts/{prompt_id}
• List prompt versions: GET https://api.openscale.so/v1/prompts/{prompt_id}/versions

List prompts

GET https://api.openscale.so/v1/prompts

Your account's prompts at their latest versions, newest first. Paged with limit, order and after (a prompt id).

Query parameters

Example request

curl https://api.openscale.so/v1/prompts \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"

Response

200: A list of prompts.

Create a prompt

POST https://api.openscale.so/v1/prompts

Save a reusable prompt as version 1. It needs instructions or input messages; {{name}} placeholders in them become the prompt's variables. Settings (model, tools, tool_choice, text, reasoning, temperature, top_p, max_output_tokens, parallel_tool_calls, truncation) apply when a request leaves them out.

Request body

Example request

curl https://api.openscale.so/v1/prompts \
  -H "Authorization: Bearer $OPENSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Support",
  "instructions": "You are a support agent for {{company}}. Answer in one paragraph.",
  "model": "deepseek/deepseek-v4.1-flash"
}'

Response

200: The prompt.

Errors

Retrieve a prompt

GET https://api.openscale.so/v1/prompts/{prompt_id}

The latest version of a prompt, or the one in ?version=.

Path parameters

Query parameters

Example request

curl https://api.openscale.so/v1/prompts/$PROMPT_ID \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"

Response

200: The prompt.

Errors

Save a new version

POST https://api.openscale.so/v1/prompts/{prompt_id}

Save the body (as in Create a prompt) as the next version; earlier versions stay as they were. name renames the prompt.

Path parameters

Request body

Example request

curl -X POST https://api.openscale.so/v1/prompts/$PROMPT_ID \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"

Response

200: The new version.

Errors

Delete a prompt

DELETE https://api.openscale.so/v1/prompts/{prompt_id}

Delete a prompt and all its versions.

Path parameters

Example request

curl -X DELETE https://api.openscale.so/v1/prompts/$PROMPT_ID \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"

Response

200: Deleted.

Errors

List prompt versions

GET https://api.openscale.so/v1/prompts/{prompt_id}/versions

Every version of a prompt, newest first. Paged with limit, order and after (a version number).

Path parameters

Query parameters

Example request

curl https://api.openscale.so/v1/prompts/$PROMPT_ID/versions \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"

Response

200: A list of versions.

Errors

More of the API reference

• API reference: base URLs, authentication and a first request.
• Chat Completions: POST /v1/chat/completions: the OpenAI Chat Completions format, streamed or not, with reasoning and tools.
• Responses: POST /v1/responses: the OpenAI Responses format with stored state, background runs and enforced tool rules.
• Conversations: Keep the turns of a Responses conversation on our side and continue it by id.
• Anthropic Messages: POST /anthropic/v1/messages: the Anthropic Messages format, for Claude Code and Anthropic SDKs.
• Models and pricing: Model ids, prices per 1M tokens, context windows, output limits, versions and the live catalog endpoint.
• Batch: Upload a JSONL file of chat completions, create a batch and collect the results when it finishes.
• Errors: The error shape, every status code and code, and which ones to retry.
• Rate limits: Requests and tokens per minute, how a 429 tells you when to retry, and how to get more.
• Data retention: What is stored, for how long, how to delete it, and zero data retention.
• Interactive reference: try every endpoint in the browser.
• OpenAPI document: the whole API as OpenAPI 3.1.