Quick Start

This guide walks you through the complete flow — from listing agents to getting an AI response.

Prerequisites

An API key (see Authentication)
A published AI agent in your dashboard
The public API running at http://localhost:3002

Step 1: List Your Agents

Find the agent you want to chat with:

Request

curl -H "X-API-Key: api_your_key" \
  http://localhost:3002/agents

Response

{
  "success": true,
  "agents": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Customer Support Agent",
      "description": "Handles customer queries",
      "state": "PUBLISHED",
      "versionNumber": 3,
      "createdAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Copy the id of the agent you want to use.

Step 2: Create a Chat Session

Request

curl -X POST \
  -H "X-API-Key: api_your_key" \
  -H "Content-Type: application/json" \
  -d '{"name": "My First Chat"}' \
  http://localhost:3002/agents/{agentId}/sessions

Response (201)

{
  "success": true,
  "session": {
    "id": "session-uuid",
    "name": "My First Chat",
    "userSessionId": "auto-generated-uuid",
    "createdAt": "2026-03-19T10:00:00.000Z"
  }
}

Copy the session id.

Step 3: Send a Message

Request

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

Response

{
  "success": true,
  "chatSession": {
    "id": "session-uuid",
    "name": "My First 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
    }
  ]
}

That's it! You now have a working AI chat conversation. Keep sending messages to the same session to continue the conversation.

What's Next?

API Reference: Agents — full endpoint details
Integration Flows — common patterns for new and resumed conversations
Error Handling — how to handle errors gracefully

Prerequisites

Step 1: List Your Agents

Step 2: Create a Chat Session

Step 3: Send a Message

What's Next?

On this page