API Reference

Conversations API

Complete API reference for sending messages, listing conversations, retrieving chat history, streaming responses, and managing conversation metadata.

The Conversations API is how your application interacts with Chatsby agents. Use it to send messages, retrieve chat history, stream real-time responses, and manage conversation lifecycle.

The Conversation Object

Field	Type	Description
`id`	string	Unique identifier (e.g., `conv_xyz789abcd`). Read-only.
`agent_id`	string	The agent this conversation belongs to.
`metadata`	object	Custom key-value pairs (max 20 keys).
`created_at`	string	ISO 8601 timestamp when the conversation started. Read-only.
`updated_at`	string	ISO 8601 timestamp of the last message. Read-only.
`messages`	array	Ordered array of Message objects. Included on single-conversation retrieval.

The Message Object

Field	Type	Description
`role`	string	Who sent the message: `user` or `assistant`.
`content`	string	The text content of the message.
`sources_used`	array	(Assistant only) Sources referenced in the response. Each object has `id` and `title`.
`timestamp`	string	ISO 8601 timestamp of the message.

Example Conversation with Messages

{
  "id": "conv_xyz789abcd",
  "agent_id": "agent_1a2b3c4d5e",
  "metadata": {
    "user_id": "usr_12345",
    "plan": "premium"
  },
  "created_at": "2025-03-15T14:30:00Z",
  "updated_at": "2025-03-15T14:32:15Z",
  "messages": [
    {
      "role": "user",
      "content": "What is your return policy?",
      "timestamp": "2025-03-15T14:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Our return policy allows returns within 30 days of purchase. Items must be in original condition with proof of purchase.",
      "sources_used": [
        { "id": "src_abc123defg", "title": "Return Policy Page" }
      ],
      "timestamp": "2025-03-15T14:30:03Z"
    },
    {
      "role": "user",
      "content": "Does that include sale items?",
      "timestamp": "2025-03-15T14:32:00Z"
    },
    {
      "role": "assistant",
      "content": "Yes, sale items can also be returned within 30 days. However, the refund will be for the sale price, not the original price.",
      "sources_used": [
        { "id": "src_abc123defg", "title": "Return Policy Page" }
      ],
      "timestamp": "2025-03-15T14:32:15Z"
    }
  ]
}

Send a Message

Sends a message to an agent and receives a response. If you provide a conversation_id, the message is appended to an existing conversation. Otherwise, a new conversation is created automatically.

POST /v1/conversations

Request Body

Parameter	Type	Required	Description
`agent_id`	string	Yes	The agent to send the message to.
`message`	string	Yes	The user's message text. Max 4,000 characters.
`conversation_id`	string	No	Continue an existing conversation. If omitted, a new conversation is created.
`metadata`	object	No	Custom key-value pairs to attach to the conversation. Only applied when creating a new conversation.
`stream`	boolean	No	Enable streaming response via Server-Sent Events. Default: `false`.

cURL — New Conversation

curl -X POST https://api.chatsby.co/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_1a2b3c4d5e",
    "message": "What is your return policy?",
    "metadata": {
      "user_id": "usr_12345",
      "source_page": "/help"
    }
  }'

cURL — Continue Existing Conversation

curl -X POST https://api.chatsby.co/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_1a2b3c4d5e",
    "message": "Does that include sale items?",
    "conversation_id": "conv_xyz789abcd"
  }'

JavaScript

const response = await fetch('https://api.chatsby.co/v1/conversations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agent_id: 'agent_1a2b3c4d5e',
    message: 'What is your return policy?',
    metadata: { user_id: 'usr_12345' },
  }),
});
 
const data = await response.json();
console.log(data.reply);
console.log(data.conversation_id); // Save this to continue the conversation

Python

import requests
 
response = requests.post(
    "https://api.chatsby.co/v1/conversations",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "agent_id": "agent_1a2b3c4d5e",
        "message": "What is your return policy?",
        "metadata": {"user_id": "usr_12345"},
    },
)
 
data = response.json()
print(data["reply"])
print(data["conversation_id"])

Response `200 OK`

{
  "id": "conv_xyz789abcd",
  "agent_id": "agent_1a2b3c4d5e",
  "reply": "Our return policy allows returns within 30 days of purchase. Items must be in original condition with proof of purchase.",
  "sources_used": [
    { "id": "src_abc123defg", "title": "Return Policy Page" }
  ],
  "conversation_id": "conv_xyz789abcd",
  "created_at": "2025-03-15T14:30:00Z"
}

Error Responses

Status	Code	Description
`400`	`missing_required_field`	The `agent_id` or `message` field is missing.
`400`	`invalid_parameter`	Message exceeds 4,000 characters or metadata has more than 20 keys.
`404`	`resource_not_found`	The specified agent or conversation does not exist.
`409`	`conflict`	The `conversation_id` belongs to a different agent than the specified `agent_id`.

Streaming Responses

Set stream: true to receive the agent's response as Server-Sent Events (SSE). This delivers tokens as they are generated, creating a real-time "typing" effect.

cURL — Streaming

curl -X POST https://api.chatsby.co/v1/conversations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_1a2b3c4d5e",
    "message": "Explain your pricing plans in detail.",
    "stream": true
  }'

The response has Content-Type: text/event-stream and delivers events in this format:

event: token
data: {"content": "Our"}

event: token
data: {"content": " pricing"}

event: token
data: {"content": " plans"}

event: token
data: {"content": " include"}

...

event: done
data: {"conversation_id": "conv_xyz789abcd", "sources_used": [{"id": "src_abc123defg", "title": "Pricing Page"}]}

JavaScript — Streaming with fetch

const response = await fetch('https://api.chatsby.co/v1/conversations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agent_id: 'agent_1a2b3c4d5e',
    message: 'Explain your pricing plans in detail.',
    stream: true,
  }),
});
 
const reader = response.body.getReader();
const decoder = new TextDecoder();
let fullResponse = '';
 
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
 
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
 
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const data = JSON.parse(line.slice(6));
      if (data.content) {
        fullResponse += data.content;
        process.stdout.write(data.content); // Print tokens as they arrive
      }
    }
  }
}

See the Streaming guide for complete implementation patterns including error handling and reconnection.

List Conversations

Retrieves a paginated list of conversations for a given agent. Conversations are returned in reverse chronological order.

GET /v1/agents/{agent_id}/conversations

Path Parameters

Parameter	Type	Description
`agent_id`	string	The agent whose conversations to list.

Query Parameters

Parameter	Type	Default	Description
`page_size`	integer	20	Results per page (1 - 100).
`cursor`	string	—	Pagination cursor from a previous response.
`created_after`	string	—	Filter: only conversations created after this ISO 8601 timestamp.
`created_before`	string	—	Filter: only conversations created before this ISO 8601 timestamp.
`metadata`	string	—	Filter by metadata. Format: `key:value`. Multiple filters: `metadata=user_id:usr_12345&metadata=plan:premium`.

cURL

curl "https://api.chatsby.co/v1/agents/agent_1a2b3c4d5e/conversations?page_size=10&created_after=2025-03-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

const params = new URLSearchParams({
  page_size: '10',
  created_after: '2025-03-01T00:00:00Z',
  metadata: 'plan:premium',
});
 
const response = await fetch(
  `https://api.chatsby.co/v1/agents/agent_1a2b3c4d5e/conversations?${params}`,
  { headers: { 'Authorization': 'Bearer YOUR_API_KEY' } }
);
 
const { data, has_more, next_cursor } = await response.json();

Response `200 OK`

{
  "data": [
    {
      "id": "conv_xyz789abcd",
      "agent_id": "agent_1a2b3c4d5e",
      "metadata": { "user_id": "usr_12345", "plan": "premium" },
      "created_at": "2025-03-15T14:30:00Z",
      "updated_at": "2025-03-15T14:32:15Z"
    },
    {
      "id": "conv_def456ghij",
      "agent_id": "agent_1a2b3c4d5e",
      "metadata": { "user_id": "usr_67890", "plan": "premium" },
      "created_at": "2025-03-14T09:15:00Z",
      "updated_at": "2025-03-14T09:20:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJpZCI6ImNvbnZfZGVmNDU2Z2hpaiJ9"
}

The list endpoint does not include the messages array in each conversation object. To get the full message history, use the Retrieve a Conversation endpoint.

Retrieve a Conversation

Retrieves a single conversation with its complete message history.

GET /v1/conversations/{conversation_id}

Path Parameters

Parameter	Type	Description
`conversation_id`	string	The unique identifier of the conversation.

cURL

curl https://api.chatsby.co/v1/conversations/conv_xyz789abcd \
  -H "Authorization: Bearer YOUR_API_KEY"

Response `200 OK`

Returns the full conversation object including the messages array (see the example above).

Error Responses

Status	Code	Description
`404`	`resource_not_found`	No conversation exists with the given ID.

Delete a Conversation

Permanently deletes a conversation and all of its messages. This action is irreversible.

DELETE /v1/conversations/{conversation_id}

Path Parameters

Parameter	Type	Description
`conversation_id`	string	The unique identifier of the conversation to delete.

cURL

curl -X DELETE https://api.chatsby.co/v1/conversations/conv_xyz789abcd \
  -H "Authorization: Bearer YOUR_API_KEY"

JavaScript

await fetch('https://api.chatsby.co/v1/conversations/conv_xyz789abcd', {
  method: 'DELETE',
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' },
});

Response `204 No Content`

No response body. The conversation and all messages have been permanently deleted.

Error Responses

Status	Code	Description
`404`	`resource_not_found`	No conversation exists with the given ID.

Metadata

Metadata lets you attach custom key-value pairs to conversations for tracking, filtering, and segmentation. See the Metadata guide for detailed usage patterns.

Key rules:

Metadata is set when a conversation is created (via the metadata parameter on the Send Message endpoint).
Maximum 20 keys per conversation.
Keys must be strings, max 40 characters.
Values must be strings, max 500 characters.
Use the metadata query parameter on the List Conversations endpoint to filter by metadata values.

Sources API Error Codes

Conversations API

The Conversation Object

The Message Object

Example Conversation with Messages

Send a Message

Request Body

cURL — New Conversation

cURL — Continue Existing Conversation

JavaScript

Python

Response 200 OK

Error Responses

Streaming Responses

cURL — Streaming

JavaScript — Streaming with fetch

List Conversations

Path Parameters

Query Parameters

cURL

JavaScript

Response 200 OK

Retrieve a Conversation

Path Parameters

cURL

Response 200 OK

Error Responses

Delete a Conversation

Path Parameters

cURL

JavaScript

Response 204 No Content

Error Responses

Metadata

Response `200 OK`

Response `200 OK`

Response `200 OK`

Response `204 No Content`