Огляд API

Кожен REST-ендпоінт RolChat дотримується одного контракту: той самий базовий URL, той самий конверт відповіді, та сама пагінація, та сама форма помилок. Розберіться в ньому один раз, і будь-яке сімейство ендпоінтів із довідника ендпоінтів читатиметься однаково.

Базовий URL і версіонування

https://api.rolchat.com/api/v1/

Версію вказано в шляху. Додавання необов’язкових полів, нових ендпоінтів чи нових параметрів запиту зі значеннями за замовчуванням не є несумісною зміною і не змінює версію. Несумісні зміни виходять як v2, а застарілі ендпоінти v1 працюють щонайменше шість місяців після оголошення (див. Виведення з експлуатації).

Автентифікація

Метод	Заголовок	Для чого
JWT bearer	`Authorization: Bearer <access_token>`	Інтерактивні сесії (вебзастосунок, мобільні застосунки)
API-ключ	`Authorization: Bearer rcp_<secret>`	Виклики між системами, API-ключі плагінів
Підпис HMAC	`X-RolChat-Signature: sha256=…`	Вхідні вебхуки з ваших систем, див. Вебхуки
Немає	-	Публічні ендпоінти віджета (`/widget/…`, `/forms/…`), обмежені сайтом і джерелом

Для інтеграцій використовуйте API-ключ (персональний токен доступу). Ключі створюються в розділі Налаштування → Плагіни → API-ключі RolChat, показуються один раз і зберігаються лише як хеш. Ключ ніколи не може зробити більше, ніж учасник, який його створив: його області доступу звіряються з поточними дозволами цього учасника під час кожного виклику. Строк дії JWT, заголовок X-Account-Id і сесії в кількох компаніях описано на сторінці Автентифікація.

Конверт відповіді

Один ресурс:

{
  "data": { "id": "cnt_01HK…", "email": "ada@example.com" },
  "meta": {
    "request_id": "req_01HK…"
  }
}

Список:

{
  "data": [ { … }, { … } ],
  "meta": {
    "request_id": "req_01HK…",
    "count": 50,
    "next_cursor": "cur_01HK…",
    "prev_cursor": "cur_01HK…",
    "has_more": true
  }
}

Відповіді без тіла (204 No Content після видалення) все одно містять заголовок X-Request-Id.

Помилка:

{
  "errors": [
    {
      "code": "validation_failed",
      "message": "Email must be valid.",
      "field": "email",
      "details": { "received": "not-an-email" }
    }
  ],
  "meta": { "request_id": "req_01HK…" }
}

code - машиночитне значення в snake_case, саме за ним варто розгалужувати логіку; message написано англійською і призначено для логів. field і details присутні, коли вони корисні, і ніколи не містять персональних даних. API ніколи не відповідає 200 з масивом errors: якщо є помилки, статус 400 або вищий. Повний список кодів - на сторінці Помилки.

Пагінація

Ендпоінти списків, які можуть зростати, використовують курсорну пагінацію. Запитайте першу сторінку без курсора, потім передавайте отриманий next_cursor без змін:

GET /api/v1/contacts?limit=50
GET /api/v1/contacts?limit=50&cursor=eyJrIjoi…

limit за замовчуванням дорівнює 50, максимум 200; більші значення відхиляються з 400 validation_failed.
Курсори непрозорі й спливають через 24 години (400 validation_failed з code: cursor_expired).
Результати узгоджені зі знімком, зробленим на першій сторінці: записи, видалені між сторінками, зникають, а нові з’являються, лише коли ви починаєте заново без курсора.
Для клієнтів, яким так зручніше, також надсилається заголовок Link з rel="next" і rel="prev".

Ідемпотентність

Надсилайте заголовок Idempotency-Key (UUID або ULID, до 255 символів) з будь-яким POST, PATCH або DELETE:

Перший запит із ключем виконується, а його статус і тіло зберігаються на 24 години.
Повтор із тим самим ключем і тим самим тілом повертає збережену відповідь без повторних побічних ефектів.
Повтор із тим самим ключем, але іншим тілом відхиляється з 409 idempotency_key_conflict.

Використовуйте його для кожного виклику, що створює щось із побічними ефектами: надсилання повідомлення, e-mail чи SMS, дзвінок, усе, за що виставляється рахунок. Запити GET завжди ідемпотентні й ігнорують цей заголовок.

Ліміти запитів

Ліміти рахуються за хвилину й застосовуються до акаунта, API-ключа або користувача (до IP-адреси на маршрутах, що не потребують входу). Ліміти за замовчуванням:

Категорія	Ліміт за замовчуванням	На хвилину
Запити без входу (за IP)	60	на IP
Користувач після входу (панель керування)	1 000	на користувача
API-ключ	1 000	на ключ
Публічні ендпоінти віджета	60 на відвідувача й 600 на мережеву адресу	на хвилину
Вхід (`/auth/login`)	5	на IP
Вхідні вебхуки	300	на хвилину
MCP-сервер	600	на хвилину
Ендпоінти OAuth	600	на хвилину

Це типові значення платформи, їх може змінити оператор; ваш план їх не збільшує, а ліміти Enterprise узгоджуються у вашому договорі. Ендпоінти з лімітами повертають:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 543

У разі перевищення ліміту відповідь - 429 з code: rate_limited у масиві errors і заголовком Retry-After у секундах. Зачекайте стільки часу перед наступним викликом. Десять невдалих спроб входу блокують акаунт на 30 хвилин.

Розміри й тайм-аути

Категорія	Макс. тіло запиту	Тайм-аут сервера
За замовчуванням	1 MB	30 s
Повідомлення з вкладеннями	25 MB	30 s
Імпорт CSV	50 MB	повертає `202` і виконується у фоні
Зображення бази знань	10 MB	30 s
Bulk API	10 MB	30 s
Пошук	1 MB	10 s
Запити до ШІ	1 MB	60 s
Ендпоінти віджета	100 KB	30 s

Завеликі тіла отримують 413 payload_too_large. Якщо висхідний сервіс не відповів вчасно, повертається 504 з code: upstream_timeout і підказкою retry_after, коли повтор може допомогти.

Типи вмісту, дати та ідентифікатори

Запити й відповіді - application/json; charset=utf-8. Завантаження файлів використовує multipart/form-data; експорт CSV повертає text/csv. Некоректний UTF-8 відхиляється з 400 validation_failed.
Мітки часу - ISO-8601 в UTC з точністю до мілісекунд: 2026-04-20T14:23:45.123Z. На вході приймається будь-яке зміщення ISO-8601, його зводять до UTC.
Ідентифікатори - непрозорі ULID або UUID. Числових ID немає, а адреси e-mail і номери телефонів ніколи не з’являються в URL.

Ізоляція клієнтів і дозволи

Кожен автентифікований запит виконується в межах одного акаунта. Ресурс, що належить іншому акаунту або сайту, на який не поширюється роль того, хто викликає, повертає 404 not_found, а не 403, щоб саме існування записів ніколи не розкривалося. Дійсний токен без потрібного дозволу (наприклад, contacts.delete) отримує 403 forbidden. Деякі дозволи мають суфікс області (conversations.read:own, :team, :all), що звужує те, що повертає список.

PATCH приймає лише змінювані поля. id, account_id, created_at, updated_at і поля стану, як-от resolved_at, доступні лише для читання; їх надсилання повертає 400 validation_failed з details.forbidden_fields. Зміна стану виконується через окремі дії, наприклад POST /tickets/:id/resolve.

Кожен запис фіксується в журналі аудиту акаунта.

Заголовки спостережуваності

Кожна відповідь містить:

X-Request-Id: req_01HK…

Записуйте X-Request-Id у лог. Це перше, про що запитає підтримка.

CORS

Джерело браузерної панелі керування - https://app.rolchat.com. Публічні ендпоінти віджета дозволяють будь-яке джерело або лише джерела, підтверджені для сайту. Виклики між серверами з API-ключем не підпадають під CORS.

Виведення з експлуатації

Зміну оголошують у журналі змін, і відповідний ендпоінт починає надсилати Deprecation: true та заголовок Sunset з датою видалення.
Публічні ендпоінти працюють щонайменше шість місяців після оголошення.
Видалення відбувається лише в новій мажорній версії. У межах v1 зміни лише додаються.

Стан сервісів

Кожен сервіс надає /healthz (живість) і /readyz (готовність).