Conversations API

Overview

The Conversations API maintains conversation state on the server. Instead of resending full message histories with every request, you create a conversation once and add items to it over time. The Responses API can reference a conversation to automatically include its items as context.

Endpoints

Method	Path	Description
POST	/:project_id/v1/conversations	Create a conversation
GET	/:project_id/v1/conversations	List conversations
GET	/:project_id/v1/conversations/{id}	Get a conversation
POST	/:project_id/v1/conversations/{id}	Update a conversation
DELETE	/:project_id/v1/conversations/{id}	Delete a conversation
POST	/:project_id/v1/conversations/{id}/items	Add an item
GET	/:project_id/v1/conversations/{id}/items	List items
GET	/:project_id/v1/conversations/{id}/items/{item_id}	Get an item
DELETE	/:project_id/v1/conversations/{id}/items/{item_id}	Delete an item

Conversations are project-scoped. All paths are relative to your project base URL: https://api.xerotier.ai/proj_ABC123

Quick Start

Create a conversation, add a system prompt, then use it with the Responses API:

Step 1: Create a conversation

                    curl -X POST https://api.xerotier.ai/proj_ABC123/v1/conversations \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"title": "Weather assistant"},
    "items": [
      {
        "type": "message",
        "role": "system",
        "content": "You are a helpful weather assistant."
      }
    ]
  }'
# Returns: {"id": "conv_abc123", ...}
                

Step 2: Add a user message

                    curl -X POST https://api.xerotier.ai/proj_ABC123/v1/conversations/conv_abc123/items \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "role": "user",
    "content": "What is the weather in Paris?"
  }'
                

Step 3: Generate a response using the conversation

                    # Responses API uses endpoint-scoped path
curl -X POST https://api.xerotier.ai/proj_ABC123/my-endpoint/v1/responses \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b",
    "input": "What is the weather in Paris?",
    "conversation": {"id": "conv_abc123"}
  }'
                

The Responses API automatically loads all conversation items as context and appends the model's response to the conversation.

Manage Conversations

Create Conversation

POST /:project_id/v1/conversations

Parameter	Type	Description
metadataoptional	object	Up to 16 key-value pairs. Keys max 64 characters, values max 512 characters.
itemsoptional	array	Initial items to add (max 20). Useful for seeding system prompts or conversation history.

Response

                        {
  "id": "conv_abc123def456",
  "object": "conversation",
  "created_at": 1709000000,
  "updated_at": 1709000000,
  "metadata": {"title": "Weather assistant"}
}
                    

List Conversations

GET /:project_id/v1/conversations

Returns a paginated list of conversations. Use cursor-based pagination with after and limit parameters.

curl

                    curl https://api.xerotier.ai/proj_ABC123/v1/conversations?limit=10 \
  -H "Authorization: Bearer xero_myproject_your_api_key"
                

Get Conversation

GET /:project_id/v1/conversations/{conversation_id}

curl

                    curl https://api.xerotier.ai/proj_ABC123/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer xero_myproject_your_api_key"
                

Update Conversation

POST /:project_id/v1/conversations/{conversation_id}

Updates the conversation metadata. The new metadata replaces the existing metadata entirely.

curl

                    curl -X POST https://api.xerotier.ai/proj_ABC123/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {"title": "Updated title", "category": "support"}
  }'
                

Delete Conversation

DELETE /:project_id/v1/conversations/{conversation_id}

Permanently deletes the conversation and all its items.

curl

                    curl -X DELETE https://api.xerotier.ai/proj_ABC123/v1/conversations/conv_abc123 \
  -H "Authorization: Bearer xero_myproject_your_api_key"
                

Manage Items

Add Item

POST /:project_id/v1/conversations/{conversation_id}/items

Parameter	Type	Description
typerequired	string	Item type: `"message"`, `"function_call"`, or `"function_call_output"`.
roleconditional	string	Required for `message` type: `"user"`, `"assistant"`, or `"system"`.
contentrequired	string	Text content of the item.
call_idconditional	string	Required for `function_call` and `function_call_output` types. Links function calls to their outputs.
nameconditional	string	Function name. Required for `function_call` type.
argumentsconditional	string	Serialized JSON arguments. Required for `function_call` type.

Message Item

curl

                    curl -X POST https://api.xerotier.ai/proj_ABC123/v1/conversations/conv_abc123/items \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "message",
    "role": "user",
    "content": "Hello, how are you?"
  }'
                

Function Call Output Item

curl

                    curl -X POST https://api.xerotier.ai/proj_ABC123/v1/conversations/conv_abc123/items \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "function_call_output",
    "call_id": "call_abc123",
    "content": "{\"temperature\": 18, \"condition\": \"sunny\"}"
  }'
                

List Items

GET /:project_id/v1/conversations/{conversation_id}/items

Returns items ordered by sequence number (ascending). Supports cursor-based pagination.

curl

                    curl https://api.xerotier.ai/proj_ABC123/v1/conversations/conv_abc123/items?limit=50 \
  -H "Authorization: Bearer xero_myproject_your_api_key"
                

Get Item

GET /:project_id/v1/conversations/{conversation_id}/items/{item_id}

curl

                    curl https://api.xerotier.ai/proj_ABC123/v1/conversations/conv_abc123/items/item_xyz789 \
  -H "Authorization: Bearer xero_myproject_your_api_key"
                

Delete Item

DELETE /:project_id/v1/conversations/{conversation_id}/items/{item_id}

Soft-deletes the item. It is excluded from future conversation context but the sequence number gap is preserved.

curl

                    curl -X DELETE https://api.xerotier.ai/proj_ABC123/v1/conversations/conv_abc123/items/item_xyz789 \
  -H "Authorization: Bearer xero_myproject_your_api_key"
                

Responses API Integration

Pass a conversation parameter when creating a response to use the conversation's items as context. The model's output is automatically appended to the conversation.

curl

                    curl -X POST https://api.xerotier.ai/proj_ABC123/my-endpoint/v1/responses \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b",
    "input": "What is the weather in Paris?",
    "conversation": {"id": "conv_abc123"}
  }'
                

Note that conversations are project-scoped (at /:project_id/v1/conversations) while the Responses API is endpoint-scoped (at /:project_id/:endpoint_slug/v1/responses).

How It Works

All active items in the conversation are loaded and prepended to the input as context.
The model generates a response using the full conversation history plus the new input.
The model's output items (messages, function calls) are automatically appended to the conversation.
The conversation's updated_at timestamp is refreshed.

Note: You can use either conversation or previous_response_id for multi-turn context, but not both in the same request. Use conversation for explicit state management and previous_response_id for simple response chaining.

Storage Tiers

Conversation content is stored using the platform's standard two-tier storage architecture. For details on storage tiers, encryption, retention, and billing, see Storage.

Conversation Storage Limits

Limit	Value
Max items per conversation	100
Max individual item size	1 MB
Max metadata keys per conversation	16
Max metadata key length	64 characters
Max metadata value length	512 characters
Max total metadata size	16 KB

Error Handling

HTTP Status	Error Code	Description
400	`invalid_request`	Missing or invalid parameters (e.g., missing role for message items).
400	`invalid_request`	Initial items array exceeds 20 items.
401	`authentication_error`	Invalid or missing API key.
404	`not_found`	Conversation or item not found.
429	`rate_limit_exceeded`	Too many requests. Check the `Retry-After` header.

Examples

Python (requests)

Python

                    import requests

headers = {
    "Authorization": "Bearer xero_myproject_your_api_key",
    "Content-Type": "application/json"
}
base = "https://api.xerotier.ai/proj_ABC123/v1"

# Create a conversation with a system prompt
conv = requests.post(f"{base}/conversations", headers=headers, json={
    "metadata": {"title": "Demo chat"},
    "items": [{
        "type": "message",
        "role": "system",
        "content": "You are a helpful assistant."
    }]
}).json()
print(f"Created conversation: {conv['id']}")

# Add a user message
requests.post(
    f"{base}/conversations/{conv['id']}/items",
    headers=headers,
    json={
        "type": "message",
        "role": "user",
        "content": "What is the capital of France?"
    }
)

# List conversations
convs = requests.get(f"{base}/conversations?limit=10", headers=headers).json()
for c in convs["data"]:
    print(f"Conversation: {c['id']}")

# List items in a conversation
items = requests.get(
    f"{base}/conversations/{conv['id']}/items?limit=50",
    headers=headers
).json()
for item in items["data"]:
    print(f"[{item['role']}] {item['content']}")

# Delete a conversation
requests.delete(f"{base}/conversations/{conv['id']}", headers=headers)
                

Node.js (fetch)

JavaScript

                    const base = "https://api.xerotier.ai/proj_ABC123/v1";
const headers = {
    "Authorization": "Bearer xero_myproject_your_api_key",
    "Content-Type": "application/json"
};

// Create a conversation with a system prompt
const convRes = await fetch(`${base}/conversations`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        metadata: { title: "Demo chat" },
        items: [{
            type: "message",
            role: "system",
            content: "You are a helpful assistant."
        }]
    })
});
const conv = await convRes.json();
console.log(`Created conversation: ${conv.id}`);

// Add a user message
await fetch(`${base}/conversations/${conv.id}/items`, {
    method: "POST",
    headers,
    body: JSON.stringify({
        type: "message",
        role: "user",
        content: "What is the capital of France?"
    })
});

// List conversations
const listRes = await fetch(`${base}/conversations?limit=10`, { headers });
const list = await listRes.json();
list.data.forEach(c => console.log(`Conversation: ${c.id}`));

// Delete a conversation
await fetch(`${base}/conversations/${conv.id}`, {
    method: "DELETE",
    headers
});
                

Multi-Turn with Function Calling (curl)

curl

                    # 1. Create conversation
curl -X POST https://api.xerotier.ai/proj_ABC123/v1/conversations \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"metadata": {"title": "Tool demo"}}'
# Returns: {"id": "conv_abc123", ...}

# 2. Generate response with tools (auto-appends to conversation)
curl -X POST https://api.xerotier.ai/proj_ABC123/my-endpoint/v1/responses \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b",
    "input": "What is the weather in Paris?",
    "conversation": {"id": "conv_abc123"},
    "tools": [{
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "Get weather for a city",
        "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}
      }
    }]
  }'

# 3. Add function output to conversation
curl -X POST https://api.xerotier.ai/proj_ABC123/v1/conversations/conv_abc123/items \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "function_call_output",
    "call_id": "call_abc123",
    "content": "{\"temperature\": 18, \"condition\": \"sunny\"}"
  }'

# 4. Continue with function result in context
curl -X POST https://api.xerotier.ai/proj_ABC123/my-endpoint/v1/responses \
  -H "Authorization: Bearer xero_myproject_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "llama-3.1-8b",
    "input": "Great, now summarize the weather.",
    "conversation": {"id": "conv_abc123"}
  }'
                