Skip to content

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

Parameter Type Location Required Description
slug string path Yes The unique identifier (slug) of your AI agent

Request Body

{
  "message": "Your message text here",
  "stream": false,
  "conversationId": "optional-conversation-id"
}
Field Type Required Description
message string Yes The message to send to the AI agent
stream boolean No Enable streaming responses (default: false)
async boolean No Enqueue the request for background processing and return a Request ID immediately via the X-Request-Id response header (default: false). See Asynchronous Mode
conversationId string No Continue an existing conversation (null for new conversation)

Response

Success (200):

{
  "data": {
    "response": "AI agent's response text",
    "conversationId": "conv_abc123",
    "metadata": {
      "model": "gpt-4",
      "tokens": 150
    }
  },
  "error": null
}

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

Alternatively, slugs are typically the lowercase, hyphenated version of your agent name: - "Customer Support" → customer-support - "Sales Bot" → sales-bot

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 conversationId from the previous response:

{
  "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/requests/{x-request-id}

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

The response returns the current status and, once ready, the final chat result.

Async Mode — Behaviour

Aspect Behaviour
Trigger async: true in POST /v1/api/chat/{slug} body
Request ID location X-Request-Id response header on the submission call
Poll endpoint GET /v1/api/chat/requests/{x-request-id}
TTL Async requests persist for 30 minutes after creation; polling after expiry returns a clear not-found response
Access scope Only the user (or service account) who created the async request can read it back
Impersonation header Both endpoints honour an optional x-user-identifier header (workspace member email or Service Account UUID) under Workspace API Tokens; ignored for User API Tokens and JWT auth
Sync compatibility async: false or omitted preserves existing sync behaviour — same response shape, headers, and status codes as before

x-user-identifier

See API Keys — Acting on Behalf of an Identity for header semantics.

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

SSE Format: 

data: {"chunk": "Hello"}
data: {"chunk": " there!"}
data: {"chunk": " How"}
data: {"chunk": " can"}
data: {"chunk": " I"}
data: {"chunk": " help"}
data: {"chunk": "?"}
data: [DONE]

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