API ReferenceConversations API

Create a conversation

Create a new conversation to store and retrieve conversation state across Response API calls **Features:** - Create conversation with optional metadata (max 16 key-value pairs) - Add up to 20 initial items to the conversation - Returns conversation ID with `conv_` prefix - Supports OpenAI Conversations API format **Metadata Constraints:** - Maximum 16 key-value pairs - Keys: max 64 characters - Values: max 512 characters

POST
/v1/conversations

Authorization

Authorization<token>

Type "Bearer" followed by a space and JWT token.

In: header

Request Body

Create conversation request with optional items and metadata

items?
metadata?
project_id?string
referrer?string
title?string

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://loading/v1/conversations" \  -H "Content-Type: application/json" \  -d '{}'
{
  "created_at": 0,
  "id": "string",
  "metadata": {
    "property1": "string",
    "property2": "string"
  },
  "object": "string",
  "project_id": "string",
  "referrer": "string",
  "title": "string",
  "updated_at": 0
}
{
  "code": "string",
  "error": "string",
  "message": "string",
  "request_id": "string"
}
{
  "code": "string",
  "error": "string",
  "message": "string",
  "request_id": "string"
}
{
  "code": "string",
  "error": "string",
  "message": "string",
  "request_id": "string"
}

Create conversation items POST

Add items to a conversation. You may add up to 20 items at a time. **Features:** - Bulk item creation (max 20 items per request) - Automatic item ID generation with `msg_` prefix - Items added to conversation's active branch (default: MAIN) - Returns list of created items with generated IDs **Item Types:** - `message`: User or assistant messages - `tool_call`: Tool/function call items - `tool_response`: Tool/function response items - Other OpenAI-compatible item types **Constraints:** - Maximum 20 items per request - Each item must have valid type and content - Items are immutable after creation

Delete a conversation item DELETE

Delete an item from a conversation. The item will be removed from the conversation. **Features:** - Remove specific item from conversation - Automatic ownership verification - Returns updated conversation object after deletion - Items are permanently removed (not soft delete) **Important:** - Deleting an item may affect conversation flow - Item IDs are not reused after deletion - Other items in conversation remain unchanged - Consider creating a new branch instead of deleting items **Response:** Returns the conversation object (not the deleted item)