Chat API¶

Send messages to AI agents and manage conversations programmatically.

Send Chat Message¶

Send a message to an AI agent and receive a response.

Endpoint: POST /chat/{slug}

Parameters¶

Request Body¶

{
  "message": "Your message text here",
  "stream": false,
  "conversationId": "optional-conversation-id"
}

Response¶

Synchronous success (200): the current schema documents a text response, with x-conversation-id and x-conversation-name headers. Do not parse this as a JSON data.response envelope.

Hello, how can I help you?

Use the returned conversation ID when continuing the conversation. Check the actual response content type and the selected streaming mode when implementing a client.

Examples¶

Basic Chat¶

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/support-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "stream": false
  }'

Continue Conversation¶

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/support-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can you elaborate on that?",
    "stream": false,
    "conversationId": "conv_abc123"
  }'

Streaming Response¶

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/support-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Tell me a long story",
    "stream": true
  }'

Error Responses¶

400 - Bad Request:

{
  "data": null,
  "error": {
    "name": "ValidationError",
    "message": "Message field is required",
    "details": {}
  }
}

401 - Unauthorized:

{
  "data": null,
  "error": {
    "name": "UnauthorizedError",
    "message": "Invalid or missing API token",
    "details": {}
  }
}

404 - Not Found:

{
  "data": null,
  "error": {
    "name": "NotFoundError",
    "message": "Agent with slug 'support-agent' not found",
    "details": {}
  }
}

Finding Your Agent Slug¶

The agent slug is the unique identifier for your agent. You can find it in the platform:

1. Navigate to My Agents
2. Click on your agent
3. The slug is shown in the agent settings or URL

Copy the actual slug from the agent URL; do not derive it from the display name.

Conversation Management¶

New Conversation¶

To start a new conversation, omit the conversationId field or set it to null:

{
  "message": "Hello",
  "conversationId": null
}

Continue Conversation¶

To continue an existing conversation, include the conversation ID from the previous response’s x-conversation-id header:

{
  "message": "Follow-up question",
  "conversationId": "conv_abc123"
}

Asynchronous Mode (Request ID)¶

For long-running chat completions where the client cannot keep an HTTP connection open, the Chat API supports an asynchronous mode. Submit with async: true, receive a Request ID immediately, then poll a separate endpoint until the result is ready.

Submitting an Async Request¶

Set async: true in the request body:

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/your-agent" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Generate a long report",
    "async": true
  }'

The server enqueues the chat for background processing and returns immediately. The Request ID is exposed via the X-Request-Id response header (not in the response body).

Polling for the Result¶

Once the chat has been enqueued, poll the status endpoint with the Request ID:

Endpoint: GET /v1/api/chat/request/{x-request-id}

curl "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/request/REQUEST_ID_FROM_HEADER" \
  -H "Authorization: Bearer YOUR_API_KEY"

The response uses top-level fields. The schema examples show processing, complete and a failure case. A completed response includes result.text:

{
  "requestId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "complete",
  "conversationId": "example-conversation-id",
  "result": {"text": "Hello!"},
  "completedAt": 1740000060000
}

Poll with a finite interval and timeout. Stop on a terminal failure; a 404 can mean missing, expired or inaccessible to the current identity. Keep the same intended identity when submitting and polling.

Async Mode — Behaviour¶

Streaming Responses¶

When stream: true is set, the response will be sent as Server-Sent Events (SSE):

curl -X POST "https://PLATFORM-URL-PLACEHOLDER/v1/api/chat/agent-slug" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello", "stream": true}' \
  --no-buffer

Process streamed content incrementally. Check the current endpoint contract and response headers before choosing a parser; do not assume the non-streaming JSON envelope or an undocumented chunk/sentinel format.

Best Practices¶

1. Store Conversation IDs: Save conversationId values to maintain context across messages
2. Handle Timeouts: Set appropriate timeouts for long-running conversations
3. Error Handling: Implement retry logic for transient errors (429, 500)
4. Rate Limiting: Respect rate limits and implement exponential backoff
5. Streaming: Use streaming for better UX with long responses

Related Topics¶

• API Overview - Authentication and base setup
• Document API - Manage knowledge base
• My Agents - Configure agents in the platform