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 (на бесплатном тарифе возвращается 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, используя команду Удерживайте для отзыва.

Эта статья ответила на ваш вопрос?