REST API
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-адреса й автентифікація
Base URL: https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKENUserJot приймає два типи токенів 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). Вони залишаються чинними, лише доки користувач, який надав дозвіл, є власником або адміністратором цього робочого простору.
Перший запит
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}після видалення згідно з GDPRDELETE /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, скориставшись кнопкою Утримуйте, щоб відкликати.