← Начало

API Документация

Интегрирайте AI агентите на Clairo във вашето приложение чрез REST API. Изисква Max план.

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

Удостоверяване

Всички API заявки изискват Bearer token. Генерирайте API ключ от таблото: Настройки → API Ключове.

API ключовете започват с clr_

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

Важно: API достъпът изисква Max план (€190/месец). Пазете ключовете си в тайна — не ги споделяйте в клиентски код.

Агенти

GET/api/v1/agents

Връща списък с всички ваши агенти.

Примерен отговор:

{
  "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

Изпраща съобщение до Support агент и получава AI отговор.

Тяло на заявката:

{
  "agentId": "cm1abc...",
  "message": "Какви са работните ви часове?",
  "conversationId": "optional-existing-id"
}

Примерен отговор:

{
  "reply": "Работим от понеделник до петък, 9:00-18:00.",
  "conversationId": "cm2xyz..."
}

Подайте conversationId за продължаване на съществуващ разговор. Ако го пропуснете, ще бъде създаден нов.

Discovery

POST/api/v1/discover

Изпраща отговор до Discovery агент. Връща следващия въпрос или завършване.

{
  "agentId": "cm1def...",
  "message": "Имаме 50 служители",
  "conversationId": "optional-existing-id"
}

Примерен отговор:

{
  "reply": "Какъв е месечният ви бюджет за софтуер?",
  "conversationId": "cm2abc...",
  "progress": 60,
  "completed": false
}

Разговори

GET/api/v1/conversations

Връща списък с разговори. Поддържа филтриране по агент.

Query параметри:

ПараметърТипОписание
agentIdstringФилтрирай по агент (незадължителен)
limitnumberБрой резултати (по подразбиране: 50)
GET/api/v1/conversations/{id}

Връща детайли за конкретен разговор с всички съобщения.

{
  "id": "cm2xyz...",
  "agentId": "cm1abc...",
  "status": "ACTIVE",
  "messages": [
    { "role": "user", "content": "Здравейте!", "createdAt": "..." },
    { "role": "assistant", "content": "Здравейте! Как мога да ви помогна?", "createdAt": "..." }
  ]
}

Резюмета (Discovery)

GET/api/v1/briefs

Връща резюмета от Discovery разговори.

{
  "briefs": [
    {
      "id": "cm3abc...",
      "agentId": "cm1def...",
      "conversationId": "cm2ghi...",
      "summary": "Иван Петров, CEO на TechStart. Търсят AI чатбот за поддръжка. Бюджет: €50-100/месец.",
      "createdAt": "2026-04-01T14:30:00Z"
    }
  ]
}
GET/api/v1/briefs/{id}

Връща детайли за конкретно резюме.

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

Срещи

POST/api/v1/meetings

Изпраща аудио за транскрипция и обобщение.

Изпратете multipart/form-data с аудио файл (webm, mp3, wav). Максимален размер: 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

Примерен отговор:

{
  "id": "cm4abc...",
  "title": "Weekly standup",
  "transcript": "Пълна транскрипция на срещата...",
  "summary": "Обобщение с ключови точки и задачи...",
  "durationSec": 2700
}

Грешки

API-то връща стандартни HTTP статус кодове. Тялото на грешката винаги съдържа error поле.

КодОписание
400Невалидна заявка — проверете параметрите
401Невалиден или липсващ API ключ
403Нямате достъп — изисква Max план
404Ресурсът не е намерен
429Прекалено много заявки — изчакайте
500Вътрешна грешка на сървъра
{
  "error": "Невалиден или липсващ API ключ"
}

Rate Limits

API-то е ограничено до 1000 заявки на минута на бизнес. Лимитите се връщат в response headers.

HeaderОписание
X-RateLimit-LimitМаксимален брой заявки на минута
X-RateLimit-RemainingОставащи заявки в текущия прозорец
X-RateLimit-ResetUnix timestamp за рестартиране на лимита

Бърз старт

Пример с 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: "Какви продукти предлагате?",
  }),
});

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

Пример с 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": "Какви продукти предлагате?",
    },
)

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

Готови да интегрирате?

Създайте акаунт и генерирайте API ключ от таблото.

Започни безплатно