REST API

Shayan TaslimОновлено

REST API UserJot надає вашому коду доступ до тих самих даних робочого простору, що й панель керування: метаданих робочого простору, дошок, запитів (зокрема об’єднань, схожих запитів, тегів, підписок і вкладень), коментарів, голосів, записів журналу змін, учасників (зокрема видалення згідно з GDPR), компаній, розмов, ресурсів, а також колекцій і статей довідкового центру.

Повний інтерактивний довідник із усіма маршрутами, схемами й прикладами доступний на сторінці userjot.com/docs/api і безпосередньо за адресою https://api.userjot.com/v1/docs. Документ OpenAPI, на основі якого його створено, доступний за адресою https://api.userjot.com/v1/openapi.json (а також у дзеркалі за адресою https://userjot.com/docs/api/openapi.json), тож ви можете генерувати типізовані клієнти своєю мовою.

Базова URL-адреса й автентифікація

text
Base URL:      https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKEN

UserJot приймає два типи токенів Bearer для маршрутів /v1/*:

  • Токени API: Створіть токен у розділі Налаштування → MCP & API (лише для адміністраторів і власників). Токени мають префікс uj_live_, належать до одного робочого простору, не втрачають чинності, доки їх не відкличуть, і їх можна перейменовувати. Щоб негайно відкликати токен, скористайтеся кнопкою Утримуйте, щоб відкликати (натисніть і утримуйте); відкликані токени залишаються у списку для аудиту.

  • Токени доступу OAuth 2.0: Підтримуються PKCE (S256), динамічна реєстрація клієнтів (/oauth/register), документи метаданих ідентифікатора клієнта (CIMD), відкликання токенів (/oauth/revoke), а також метадані виявлення за адресами https://api.userjot.com/.well-known/oauth-authorization-server і https://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. Термін дії токенів доступу становить 1 годину, а токенів оновлення з ротацією — 30 днів (області дії workspace і offline_access). Вони залишаються чинними, лише доки користувач, який надав дозвіл, є власником або адміністратором цього робочого простору.

Перший запит

Bash
curl https://api.userjot.com/v1/boards \
  -H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"

Обмеження частоти запитів

Запити API та MCP використовують спільний ліміт запитів робочого простору:

План

За хвилину

За годину

Free

10 запитів

150 запитів

Starter

60 запитів

1 500 запитів

Professional

120 запитів

5 000 запитів

Також діють додаткові ліміти для окремих операцій:

  • Ресурси: Імпорт ресурсів, багаточастинне завантаження й автоматично імпортовані зображення Markdown використовують окремий ліміт робочого простору: 20 запитів на хвилину і 300 на годину (а для завершення завантаження діють додаткові ліміти 20 на хвилину і 300 на годину).

  • Вихідні розмови (POST /v1/conversations): доступні лише на платних тарифах. Ліміт — 5 на день на тарифі Starter і 15 на день на тарифі Professional (на тарифі Free повертається 409 plan_feature_unavailable).

У разі перевищення ліміту API повертає HTTP 429 із заголовком Retry-After та error.details.retry_after_seconds.

Пагінація, помилки та ідемпотентність

  • Пагінація за курсором. Кінцеві точки для списків приймають cursor і limit (до 100; значення за замовчуванням залежать від кінцевої точки, наприклад 10 для розгорнутих списків на кшталт /v1/requests і /v1/changelogs) і повертають next_cursor для переходу до наступної сторінки.

  • Формат помилок. У відповідях із помилками повертається { "error": { "code", "message", "details" } }, а кожна відповідь містить заголовок X-Request-Id. Серед поширених кодів: 422 validation_error (разом із details.issues), 409 plan_limit_reached, 409 plan_feature_unavailable, 409 request_merged, 410 member_erased (для GET/PATCH /v1/members/{member_id} після видалення згідно з GDPR DELETE /v1/members/{member_id}), 409 member_erased (для маршрутів, що посилаються на видаленого учасника), 409 help_slug_taken і 409 help_version_conflict.

  • Ідемпотентність. Додавайте заголовок Idempotency-Key (він зберігається 24 години разом із відбитком тіла запиту), щоб безпечно повторювати запити на створення для восьми маршрутів: /v1/requests, /v1/changelogs, /v1/conversations, /v1/conversations/{conversation_id}/replies, /v1/conversations/{conversation_id}/notes, /v1/assets/import, /v1/help/articles і /v1/help/collections.

Ресурси та зображення

Зображення (PNG, JPEG, GIF або WebP розміром до 10 MiB) можна завантажити трьома способами:

  • Багаточастинне завантаження: POST /v1/assets (createAsset, лише REST API) завантажує зображення одним запитом multipart/form-data.

  • Імпорт за URL-адресою: POST /v1/assets/import завантажує загальнодоступне зображення HTTPS у сховище робочого простору.

  • Триетапне завантаження за попередньо підписаною URL-адресою: POST /v1/assets/uploads (потрібно вказати точний size_bytes; не більше 100 відкритих сеансів завантаження на робочий простір) → передайте байти PUT за попередньо підписаною URL-адресою, чинною 30 хвилин → POST /v1/assets/uploads/{upload_id}/complete.

Посилайтеся на завантажені ресурси в Markdown за допомогою asset:<id>. Загальнодоступні URL-адреси зображень HTTPS, вбудовані в Markdown і надіслані до кінцевих точок журналу змін і статей довідки, також імпортуються автоматично (до 10 вбудованих зображень на запит журналу змін і до 20 на запит статті довідкового центру). Їх кількість враховується в ліміті ресурсів робочого простору.

Вебхуки

Вихідні вебхуки для клієнтів поки що недоступні. Щоб отримувати сповіщення команди в реальному часі, скористайтеся Підключити Slack або Підключити Discord чи перевіряйте зміни за допомогою REST API.

REST чи MCP

Сервер MCP побудовано на основі цього API. Він надає 98 зі 100 операцій REST як інструменти MCP (POST /v1/assets багаточастинне завантаження й DELETE /v1/members/{member_id} видалення згідно з GDPR доступні лише через REST). Використовуйте REST API у власному серверному застосунку, автоматизації або коді застосунку, якщо вам потрібен повний контроль над запитами й відповідями. Використовуйте MCP для підключення AI-клієнта, який підтримує протокол Model Context Protocol.

Робота з токенами

Ставтеся до токена API як до будь-якого іншого секрету:

  • Не додавайте його безпосередньо до файлів конфігурації, які зберігаються в системі контролю версій.

  • Надавайте перевагу змінним середовища або менеджеру секретів.

  • За можливості використовуйте окремі токени для різних середовищ або учасників команди.

  • Відкликайте непотрібні токени в розділі Налаштування → MCP & API, скориставшись кнопкою Утримуйте, щоб відкликати.

Чи відповіла ця стаття на ваше запитання?