← Home

API Documentation

Integrate Clairo's AI agents into your application via REST API. Requires the Max plan.

Base URL: https://clairo.tech/api/v1

Authentication

All API requests require a Bearer token. Generate an API key from the dashboard: Settings → API Keys.

API keys start with clr_

curl -H "Authorization: Bearer clr_your_api_key" \
  https://clairo.tech/api/v1/agents

Important: API access requires the Max plan (€190/month). Keep your keys secret — never expose them in client-side code.

Agents

GET/api/v1/agents

Returns a list of all your agents.

Example response:

{
  "agents": [
    {
      "id": "cm1abc...",
      "name": "Support Bot",
      "type": "SUPPORT",
      "isActive": true,
      "description": "Customer support agent",
      "createdAt": "2026-01-15T10:00:00Z"
    }
  ]
}

Chat

POST/api/v1/chat

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

Request body:

{
  "agentId": "cm1abc...",
  "message": "What are your business hours?",
  "conversationId": "optional-existing-id"
}

Example response:

{
  "reply": "We are open Monday to Friday, 9am-6pm.",
  "conversationId": "cm2xyz..."
}

Pass conversationId to continue an existing conversation. If omitted, a new one will be created.

Discovery

POST/api/v1/discover

Send an answer to a Discovery agent. Returns the next question or completion.

{
  "agentId": "cm1def...",
  "message": "We have 50 employees",
  "conversationId": "optional-existing-id"
}

Example response:

{
  "reply": "What is your monthly software budget?",
  "conversationId": "cm2abc...",
  "progress": 60,
  "completed": false
}

Conversations

GET/api/v1/conversations

Returns a list of conversations. Supports filtering by agent.

Query parameters:

ParameterTypeDescription
agentIdstringFilter by agent (optional)
limitnumberNumber of results (default: 50)
GET/api/v1/conversations/{id}

Returns details of a specific conversation with all messages.

{
  "id": "cm2xyz...",
  "agentId": "cm1abc...",
  "status": "ACTIVE",
  "messages": [
    { "role": "user", "content": "Hello!", "createdAt": "..." },
    { "role": "assistant", "content": "Hi! How can I help?", "createdAt": "..." }
  ]
}

Briefs (Discovery)

GET/api/v1/briefs

Returns briefs from Discovery conversations.

{
  "briefs": [
    {
      "id": "cm3abc...",
      "agentId": "cm1def...",
      "conversationId": "cm2ghi...",
      "summary": "John Smith, CEO of TechStart. Looking for AI chatbot for support. Budget: $50-100/month.",
      "createdAt": "2026-04-01T14:30:00Z"
    }
  ]
}
GET/api/v1/briefs/{id}

Returns details of a specific brief.

{
  "id": "cm3abc...",
  "summary": "...",
  "answers": { ... },
  "conversation": { "id": "...", "messages": [...] }
}

Meetings

POST/api/v1/meetings

Submit audio for transcription and summarization.

Send multipart/form-data with an audio file (webm, mp3, wav). Max size: 25MB.

curl -X POST \
  -H "Authorization: Bearer clr_your_api_key" \
  -F "agentId=cm1ghi..." \
  -F "audio=@meeting.webm" \
  -F "title=Weekly standup" \
  https://clairo.tech/api/v1/meetings

Example response:

{
  "id": "cm4abc...",
  "title": "Weekly standup",
  "transcript": "Full meeting transcript...",
  "summary": "Summary with key points and action items...",
  "durationSec": 2700
}

Error Handling

The API returns standard HTTP status codes. Error responses always include an error field.

CodeDescription
400Bad Request — check your parameters
401Invalid or missing API key
403Forbidden — requires Max plan
404Resource not found
429Too many requests — slow down
500Internal server error
{
  "error": "Missing or invalid Authorization header. Use: Bearer clr_..."
}

Rate Limits

The API is limited to 1,000 requests per minute per business. Limits are returned in response headers.

HeaderDescription
X-RateLimit-LimitMaximum requests per minute
X-RateLimit-RemainingRemaining requests in current window
X-RateLimit-ResetUnix timestamp when the limit resets

Quick Start

Example with JavaScript (Node.js):

const API_KEY = "clr_your_api_key";
const BASE_URL = "https://clairo.tech/api/v1";

// Send a chat message
const response = await fetch(`${BASE_URL}/chat`, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    agentId: "your_agent_id",
    message: "What products do you offer?",
  }),
});

const data = await response.json();
console.log(data.reply);

Example with Python:

import requests

API_KEY = "clr_your_api_key"
BASE_URL = "https://clairo.tech/api/v1"

response = requests.post(
    f"{BASE_URL}/chat",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "agentId": "your_agent_id",
        "message": "What products do you offer?",
    },
)

data = response.json()
print(data["reply"])

Ready to integrate?

Create an account and generate an API key from the dashboard.

Get started