# Conversations API

Keep the turns of a Responses conversation on our side and continue it by id.

Stored conversations for the Responses API: create them, add and remove items, and use them with `conversation`.

## Endpoints

- [Create a conversation](#create-a-conversation): `POST https://api.openscale.so/v1/conversations`
- [Retrieve a conversation](#retrieve-a-conversation): `GET https://api.openscale.so/v1/conversations/{conversation_id}`
- [Update a conversation](#update-a-conversation): `POST https://api.openscale.so/v1/conversations/{conversation_id}`
- [Delete a conversation](#delete-a-conversation): `DELETE https://api.openscale.so/v1/conversations/{conversation_id}`
- [List items](#list-items): `GET https://api.openscale.so/v1/conversations/{conversation_id}/items`
- [Add items](#add-items): `POST https://api.openscale.so/v1/conversations/{conversation_id}/items`
- [Retrieve an item](#retrieve-an-item): `GET https://api.openscale.so/v1/conversations/{conversation_id}/items/{item_id}`
- [Delete an item](#delete-an-item): `DELETE https://api.openscale.so/v1/conversations/{conversation_id}/items/{item_id}`

### Create a conversation

`POST https://api.openscale.so/v1/conversations`

A stored conversation, with up to 20 initial `items` and `metadata` (up to 16 string pairs). Use its id as `conversation` in Create a response. Conversations are kept until you delete them.

#### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | No |  |
| `metadata` | object | No |  |

#### Example request

```bash
curl https://api.openscale.so/v1/conversations \
  -H "Authorization: Bearer $OPENSCALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "metadata": {
    "topic": "support"
  },
  "items": [
    {
      "type": "message",
      "role": "user",
      "content": "Hello!"
    }
  ]
}'
```

#### Response

`200`: The conversation.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Example: `conv_example`. |
| `object` | string | Always `conversation`. |
| `created_at` | integer |  |
| `metadata` | object |  |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid items or metadata. |

### Retrieve a conversation

`GET https://api.openscale.so/v1/conversations/{conversation_id}`

#### Path parameters

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

#### Example request

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

#### Response

`200`: The conversation.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Example: `conv_example`. |
| `object` | string | Always `conversation`. |
| `created_at` | integer |  |
| `metadata` | object |  |

#### Errors

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

### Update a conversation

`POST https://api.openscale.so/v1/conversations/{conversation_id}`

Replace the conversation metadata.

#### Path parameters

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

#### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `metadata` | object | Yes |  |

#### Example request

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

#### Response

`200`: The conversation.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Example: `conv_example`. |
| `object` | string | Always `conversation`. |
| `created_at` | integer |  |
| `metadata` | object |  |

#### Errors

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

### Delete a conversation

`DELETE https://api.openscale.so/v1/conversations/{conversation_id}`

Delete the conversation and all of its items at once.

#### Path parameters

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

#### Example request

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

#### Response

`200`: Deleted.

```json
{
  "id": "conv_example",
  "object": "conversation.deleted",
  "deleted": true
}
```

#### Errors

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

### List items

`GET https://api.openscale.so/v1/conversations/{conversation_id}/items`

Paged with `limit` (1 to 100, default 20), `order` (`desc` by default) and `after` (an item id).

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_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/conversations/$CONVERSATION_ID/items \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"
```

#### Response

`200`: A list of items.

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Always `list`. |
| `data` | array of object |  |
| `first_id` | string or null |  |
| `last_id` | string or null |  |
| `has_more` | boolean |  |

#### Errors

| Status | Meaning |
| --- | --- |
| 404 | No conversation (or `after` item) with this id. |

### Add items

`POST https://api.openscale.so/v1/conversations/{conversation_id}/items`

Add up to 20 items to the end of the conversation.

#### Path parameters

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

#### Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `items` | array of object | Yes |  |

#### Example request

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

#### Response

`200`: The added items.

| Field | Type | Description |
| --- | --- | --- |
| `object` | string | Always `list`. |
| `data` | array of object |  |
| `first_id` | string or null |  |
| `last_id` | string or null |  |
| `has_more` | boolean |  |

#### Errors

| Status | Meaning |
| --- | --- |
| 400 | Invalid items, or an item already in the conversation. |
| 404 | No conversation with this id. |

### Retrieve an item

`GET https://api.openscale.so/v1/conversations/{conversation_id}/items/{item_id}`

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_id` | string | Yes |  |
| `item_id` | string | Yes |  |

#### Example request

```bash
curl https://api.openscale.so/v1/conversations/$CONVERSATION_ID/items/$ITEM_ID \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"
```

#### Response

`200`: The item.

#### Errors

| Status | Meaning |
| --- | --- |
| 404 | No such conversation or item. |

### Delete an item

`DELETE https://api.openscale.so/v1/conversations/{conversation_id}/items/{item_id}`

Delete one item; answers with the conversation.

#### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `conversation_id` | string | Yes |  |
| `item_id` | string | Yes |  |

#### Example request

```bash
curl -X DELETE https://api.openscale.so/v1/conversations/$CONVERSATION_ID/items/$ITEM_ID \
  -H "Authorization: Bearer $OPENSCALE_API_KEY"
```

#### Response

`200`: The conversation.

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | Example: `conv_example`. |
| `object` | string | Always `conversation`. |
| `created_at` | integer |  |
| `metadata` | object |  |

#### Errors

| Status | Meaning |
| --- | --- |
| 404 | No such conversation or item. |

## 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.
- [Prompts](https://openscale.so/docs/prompts): Save instructions, messages and settings once, then use them by id in the Responses API.
- [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.