Create conversation items
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
Type "Bearer" followed by a space and JWT token.
In: header
Path Parameters
Conversation ID (format: conv_xxxxx)
Query Parameters
Additional fields to include in response
Create items request with array of items
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://loading/v1/conversations/string/items" \ -H "Content-Type: application/json" \ -d '{ "items": [ {} ] }'{
"data": [
{
"acknowledged_safety_checks": [
{
"reason": "string",
"type": "string"
}
],
"action": {},
"approval_request_id": "string",
"approve": true,
"arguments": "string",
"branch": "string",
"call_id": "string",
"commands": [
"string"
],
"completed_at": "string",
"content": [
{
"audio": {
"data": "string",
"format": "string",
"id": "string",
"transcript": "string"
},
"code": {
"code": "string",
"error": "string",
"execution_id": "string",
"exit_code": 0,
"language": "string",
"metadata": {
"property1": null,
"property2": null
},
"output": "string"
},
"computer_action": {
"action": "string",
"coordinates": {
"x": 0,
"y": 0
},
"key": "string",
"metadata": {
"property1": null,
"property2": null
},
"scroll_delta": {
"x": 0,
"y": 0
},
"text": "string"
},
"computer_screenshot": {
"description": "string",
"height": 0,
"image_data": "string",
"image_url": "string",
"timestamp": 0,
"width": 0
},
"file": {
"file_id": "string",
"mime_type": "string",
"name": "string",
"size": 0
},
"finish_reason": "string",
"function_call": {
"arguments": "string",
"id": "string",
"name": "string"
},
"function_call_output": {
"call_id": "string",
"output": "string"
},
"image": {
"detail": "string",
"file_id": "string",
"url": "string"
},
"input_audio": {
"data": "string",
"format": "string",
"transcript": "string"
},
"output_text": {
"annotations": [
{
"bounding_box": {
"height": 0,
"width": 0,
"x": 0,
"y": 0
},
"confidence": 0,
"container_id": "string",
"end_index": 0,
"file_id": "string",
"filename": "string",
"index": 0,
"page_number": 0,
"quote": "string",
"start_index": 0,
"text": "string",
"type": "string",
"url": "string"
}
],
"logprobs": [
{
"bytes": [
0
],
"logprob": 0,
"token": "string",
"top_logprobs": [
{
"bytes": [
0
],
"logprob": 0,
"token": "string"
}
]
}
],
"text": "string"
},
"refusal": "string",
"summary_text": "string",
"thinking": "string",
"tool_call_id": "string",
"tool_calls": [
{
"function": {
"arguments": "string",
"id": "string",
"name": "string"
},
"id": "string",
"type": "string"
}
],
"type": "string"
}
],
"created_at": "string",
"error": "string",
"id": "string",
"incomplete_at": "string",
"incomplete_details": {
"error": "string",
"reason": "string"
},
"max_output_length": 0,
"name": "string",
"object": "string",
"operation": {},
"output": "string",
"pending_safety_checks": [
{
"reason": "string",
"type": "string"
}
],
"rated_at": "string",
"rating": "like",
"rating_comment": "string",
"reason": "string",
"role": "system",
"sequence_number": 0,
"server_label": "string",
"shell_outputs": [
{
"type": "string",
"value": "string"
}
],
"status": "incomplete",
"tools": [
{
"annotations": null,
"description": "string",
"input_schema": null,
"name": "string"
}
],
"type": "message"
}
],
"first_id": "string",
"has_more": true,
"last_id": "string",
"object": "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"
}{
"code": "string",
"error": "string",
"message": "string",
"request_id": "string"
}Get a conversation GET
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
Create a conversation POST
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