API ReferenceConversations API

Get a conversation

Retrieve a conversation by ID with ownership verification **Features:** - Retrieves conversation metadata including creation timestamp - Automatic ownership verification (user can only access their own conversations) - Returns OpenAI-compatible conversation object **Response Fields:** - `id`: Conversation ID with `conv_` prefix - `object`: Always "conversation" - `created_at`: Unix timestamp - `metadata`: User-defined key-value pairs

GET
/v1/conversations/{conv_public_id}

Authorization

Authorization<token>

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

In: header

Path Parameters

conv_public_idstring

Conversation ID (format: conv_xxxxx)

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://loading/v1/conversations/string"
{
  "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"
}
{
  "code": "string",
  "error": "string",
  "message": "string",
  "request_id": "string"
}

Get a conversation item GET

Retrieve a single item from a conversation by item ID **Features:** - Retrieve specific item by ID - Returns complete item with all content - Automatic ownership verification via conversation - Optional include parameter for additional fields **Response Fields:** - `id`: Item ID with `msg_` prefix - `type`: Item type (message, tool_call, etc.) - `role`: Role for message items (user, assistant) - `content`: Item content array - `status`: Item status (completed, incomplete, etc.) - `created_at`: Unix timestamp

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