# Prompts API

Save instructions, messages and settings once, then use them by id in the Responses 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`.

| Endpoint | Does |
| --- | --- |
| `POST /v1/prompts` | Create a prompt (version `1`) |
| `POST /v1/prompts/{id}` | Save a new version (versions never change) |
| `GET /v1/prompts/{id}` | The latest version, or `?version=` |
| `GET /v1/prompts`, `GET /v1/prompts/{id}/versions` | List prompts, or a prompt's versions |
| `DELETE /v1/prompts/{id}` | Delete a prompt and all its versions |

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

## Endpoints

- [List prompts](#list-prompts): `GET https://api.openscale.so/v1/prompts`
- [Create a prompt](#create-a-prompt): `POST https://api.openscale.so/v1/prompts`
- [Retrieve a prompt](#retrieve-a-prompt): `GET https://api.openscale.so/v1/prompts/{prompt_id}`
- [Save a new version](#save-a-new-version): `POST https://api.openscale.so/v1/prompts/{prompt_id}`
- [Delete a prompt](#delete-a-prompt): `DELETE https://api.openscale.so/v1/prompts/{prompt_id}`
- [List prompt versions](#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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | From 1 to 100. Default `20`. |
| `order` | string | No | One of `asc`, `desc`. Default `"desc"`. |
| `after` | string | No |  |

#### Example request

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

#### Response

`200`: A list of prompts.

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Always `list`. |
| `data` | array of object |  |
| `data[].id` | string | Example: `pmpt_9f2c...`. |
| `data[].object` | string | Always `prompt`. |
| `data[].name` | string or null |  |
| `data[].version` | string | Example: `2`. |
| `data[].latest_version` | string |  |
| `data[].variables` | array of string |  |
| `data[].created_at` | integer |  |
| `data[].version_created_at` | integer |  |
| `first_id` | string or null |  |
| `last_id` | string or null |  |
| `has_more` | boolean |  |

### 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Up to 256 characters. |
| `instructions` | string | No |  |
| `input` | any | No | A string (one user message) or a list of messages. |
| `model` | string | No |  |
| `tools` | array of object | No |  |
| `tool_choice` | any | No |  |
| `text` | object | No |  |
| `reasoning` | object | No |  |
| `temperature` | number | No |  |
| `top_p` | number | No |  |
| `max_output_tokens` | integer | No |  |
| `parallel_tool_calls` | boolean | No |  |
| `truncation` | string | No | One of `auto`, `disabled`. |

#### Example request

```bash
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.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Example: `pmpt_9f2c...`. |
| `object` | string | Always `prompt`. |
| `name` | string or null |  |
| `version` | string | Example: `2`. |
| `latest_version` | string |  |
| `variables` | array of string |  |
| `created_at` | integer |  |
| `version_created_at` | integer |  |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid prompt; `param` names the field. |
| 401 | Missing or invalid API key. |

### 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `prompt_id` | string | Yes |  |

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | string | No |  |

#### Example request

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

#### Response

`200`: The prompt.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Example: `pmpt_9f2c...`. |
| `object` | string | Always `prompt`. |
| `name` | string or null |  |
| `version` | string | Example: `2`. |
| `latest_version` | string |  |
| `variables` | array of string |  |
| `created_at` | integer |  |
| `version_created_at` | integer |  |

#### Errors

| Status | Meaning |
| --- | --- |
| 404 | No prompt (or version) with this id. |

### 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `prompt_id` | string | Yes |  |

#### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | No | Up to 256 characters. |
| `instructions` | string | No |  |
| `input` | any | No | A string (one user message) or a list of messages. |
| `model` | string | No |  |
| `tools` | array of object | No |  |
| `tool_choice` | any | No |  |
| `text` | object | No |  |
| `reasoning` | object | No |  |
| `temperature` | number | No |  |
| `top_p` | number | No |  |
| `max_output_tokens` | integer | No |  |
| `parallel_tool_calls` | boolean | No |  |
| `truncation` | string | No | One of `auto`, `disabled`. |

#### Example request

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

#### Response

`200`: The new version.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Example: `pmpt_9f2c...`. |
| `object` | string | Always `prompt`. |
| `name` | string or null |  |
| `version` | string | Example: `2`. |
| `latest_version` | string |  |
| `variables` | array of string |  |
| `created_at` | integer |  |
| `version_created_at` | integer |  |

#### Errors

| Status | Meaning |
| --- | --- |
| 404 | No prompt with this id. |

### Delete a prompt

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

Delete a prompt and all its versions.

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `prompt_id` | string | Yes |  |

#### Example request

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

#### Response

`200`: Deleted.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string |  |
| `object` | string | Always `prompt.deleted`. |
| `deleted` | boolean |  |

#### Errors

| Status | Meaning |
| --- | --- |
| 404 | No prompt with this id. |

### 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

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `prompt_id` | string | Yes |  |

#### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | No | From 1 to 100. Default `20`. |
| `order` | string | No | One of `asc`, `desc`. Default `"desc"`. |
| `after` | string | No |  |

#### Example request

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

#### Response

`200`: A list of versions.

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Always `list`. |
| `data` | array of object |  |
| `data[].id` | string | Example: `pmpt_9f2c...`. |
| `data[].object` | string | Always `prompt`. |
| `data[].name` | string or null |  |
| `data[].version` | string | Example: `2`. |
| `data[].latest_version` | string |  |
| `data[].variables` | array of string |  |
| `data[].created_at` | integer |  |
| `data[].version_created_at` | integer |  |
| `first_id` | string or null |  |
| `last_id` | string or null |  |
| `has_more` | boolean |  |

#### Errors

| Status | Meaning |
| --- | --- |
| 404 | No prompt with this id. |

## More of the API reference

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