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 (на бесплатном тарифе возвращается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 МиБ) тремя способами:
Загрузка по частям:
POST /v1/assets(createAsset, только REST) загружает изображение одним запросом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 для подключения ИИ-клиента, поддерживающего Model Context Protocol.
Работа с токенами
Обращайтесь с токеном API как с любым другим секретом:
Не указывайте его напрямую в файлах конфигурации, добавляемых в репозиторий.
По возможности используйте переменные окружения или менеджер секретов.
По возможности используйте отдельные токены для разных окружений или участников команды.
Отзывайте ненужные токены в разделе Настройки → MCP & API, используя команду Удерживайте для отзыва.