Conversations API

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

Endpoints

• Create a conversation: POST https://api.openscale.so/v1/conversations
• Retrieve a conversation: GET https://api.openscale.so/v1/conversations/{conversation_id}
• Update a conversation: POST https://api.openscale.so/v1/conversations/{conversation_id}
• Delete a conversation: DELETE https://api.openscale.so/v1/conversations/{conversation_id}
• List items: GET https://api.openscale.so/v1/conversations/{conversation_id}/items
• Add items: POST https://api.openscale.so/v1/conversations/{conversation_id}/items
• Retrieve an item: GET https://api.openscale.so/v1/conversations/{conversation_id}/items/{item_id}
• 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

Example request

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.

Errors

Retrieve a conversation

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

Path parameters

Example request

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

Response

200: The conversation.

Errors

Update a conversation

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

Replace the conversation metadata.

Path parameters

Request body

Example request

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

Response

200: The conversation.

Errors

Delete a conversation

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

Delete the conversation and all of its items at once.

Path parameters

Example request

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

Response

200: Deleted.

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

Errors

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

Query parameters

Example request

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

Response

200: A list of items.

Errors

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

Request body

Example request

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

Response

200: The added items.

Errors

Retrieve an item

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

Path parameters

Example request

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

Response

200: The item.

Errors

Delete an item

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

Delete one item; answers with the conversation.

Path parameters

Example request

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

Response

200: The conversation.

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