Messages

The messages endpoints are the core of the Headless Chat API. Send a user message and receive an AI response powered by the agent's knowledge base.

Send a Message

Sends a user message to the AI agent and returns the AI response. The agent uses RAG (Retrieval-Augmented Generation) to find relevant content from its knowledge base before generating a response.

Request

POST /agents/{agentId}/sessions/{sessionId}/messages

Path Parameters

Parameter	Type	Required	Description
`agentId`	string (UUID)	Yes	The agent ID
`sessionId`	string (UUID)	Yes	The session ID

Request Body

Field	Type	Required	Description
`message`	string	Yes	The user's message
`additionalContext`	string	No	Extra context (e.g. page content) to help the AI generate a more relevant response
`format`	`"markdown"` \| `"html"`	No	Response format. Default: `"markdown"`

Basic Example

{
  "message": "What is your return policy?"
}

With Options

{
  "message": "What is your return policy?",
  "additionalContext": "The user is currently on the checkout page.",
  "format": "html"
}

Response

200 OK

{
  "success": true,
  "chatSession": {
    "id": "session-uuid",
    "name": "Support Chat"
  },
  "userMessage": {
    "id": "msg-uuid-1",
    "role": "USER",
    "content": "What is your return policy?",
    "createdAt": "2026-03-19T10:00:00.000Z"
  },
  "aiMessage": {
    "id": "msg-uuid-2",
    "role": "AI",
    "content": "Our return policy allows returns within 30 days...",
    "model": "gpt-4o-mini",
    "createdAt": "2026-03-19T10:00:01.000Z"
  },
  "followUps": [
    {
      "id": "followup-1",
      "text": "How long do refunds take?",
      "confidence": 0.9
    }
  ]
}

Response Fields

Field	Type	Description
`chatSession`	object	Session ID and name
`userMessage`	object	The saved user message with its ID and timestamp
`aiMessage`	object	The AI response with content, model used, and timestamp
`aiMessage.model`	string	The LLM model used (e.g. `"gpt-4o-mini"`)
`followUps`	array	Suggested follow-up questions (if enabled on the agent)
`followUps[].text`	string	The suggested question
`followUps[].confidence`	number	Confidence score (0–1)

Code Examples

cURL

curl -X POST \
  -H "X-API-Key: api_your_key" \
  -H "Content-Type: application/json" \
  -d '{"message": "What is your return policy?"}' \
  http://localhost:3002/agents/{agentId}/sessions/{sessionId}/messages

Node.js

const res = await fetch(
  `http://localhost:3002/agents/${agentId}/sessions/${sessionId}/messages`,
  {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.API_KEY!,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      message: 'What is your return policy?'
    })
  }
);
const data = await res.json();

console.log('AI:', data.aiMessage.content);

// Show follow-up suggestions
for (const followUp of data.followUps) {
  console.log(`  → ${followUp.text}`);
}

Python

import requests

res = requests.post(
    f'http://localhost:3002/agents/{agent_id}/sessions/{session_id}/messages',
    headers={
        'X-API-Key': 'api_your_key',
        'Content-Type': 'application/json'
    },
    json={'message': 'What is your return policy?'}
)
data = res.json()
print('AI:', data['aiMessage']['content'])

Get Message History

Returns paginated message history for a chat session.

Request

GET /agents/{agentId}/sessions/{sessionId}/messages

Query Parameters

Parameter	Type	Default	Description
`cursor`	string (UUID)	—	Message ID to start after (for pagination). Omit for the first page.
`limit`	integer	50	Messages per page (min: 1, max: 100)

Response

200 OK

{
  "success": true,
  "messages": [
    {
      "id": "msg-1",
      "role": "USER",
      "content": "Hello!",
      "type": "TEXT",
      "createdAt": "2026-03-19T10:00:00.000Z"
    },
    {
      "id": "msg-2",
      "role": "AI",
      "content": "Hi there! How can I help?",
      "type": "TEXT",
      "createdAt": "2026-03-19T10:00:01.000Z"
    }
  ],
  "pagination": {
    "hasMore": false,
    "nextCursor": null,
    "total": 2
  }
}

Pagination

Use cursor-based pagination to navigate through large message histories:

First page

curl -H "X-API-Key: api_your_key" \
  "http://localhost:3002/agents/{agentId}/sessions/{sessionId}/messages?limit=10"

Next page (using nextCursor from previous response)

curl -H "X-API-Key: api_your_key" \
  "http://localhost:3002/agents/{agentId}/sessions/{sessionId}/messages?cursor=msg-10&limit=10"

Code Examples

Node.js — Fetch all messages

async function getAllMessages(agentId: string, sessionId: string) {
  const messages = [];
  let cursor: string | null = null;

  do {
    const params = new URLSearchParams({ limit: '50' });
    if (cursor) params.set('cursor', cursor);

    const res = await fetch(
      `http://localhost:3002/agents/${agentId}/sessions/${sessionId}/messages?${params}`,
      { headers: { 'X-API-Key': process.env.API_KEY! } }
    );
    const data = await res.json();

    messages.push(...data.messages);
    cursor = data.pagination.nextCursor;
  } while (cursor);

  return messages;
}

On this page