REST API
REST API UserJot udostępnia Twojemu kodowi te same dane obszaru roboczego co panel: metadane obszaru roboczego, tablice, zgłoszenia (w tym połączone zgłoszenia, podobne zgłoszenia, tagi, subskrypcje i załączniki), komentarze, głosy, wpisy dziennika zmian, członków (w tym usuwanie danych zgodnie z RODO), firmy, rozmowy, zasoby oraz kolekcje i artykuły centrum pomocy.
Pełna interaktywna dokumentacja, zawierająca wszystkie endpointy, schematy i przykłady, jest dostępna pod adresem userjot.com/docs/api oraz bezpośrednio pod adresem https://api.userjot.com/v1/docs. Dokument OpenAPI, na którym się opiera, znajduje się pod adresem https://api.userjot.com/v1/openapi.json (jest też dostępny pod adresem https://userjot.com/docs/api/openapi.json), dzięki czemu możesz generować typowane klienty w swoim języku.
Podstawowy adres URL i uwierzytelnianie
Base URL: https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKENUserJot akceptuje dwa typy tokenów Bearer na trasach /v1/*:
Tokeny API: Utwórz token w sekcji Ustawienia → MCP & API (tylko administratorzy i właściciele). Tokeny mają prefiks
uj_live_, są przypisane do jednego obszaru roboczego, nie wygasają, dopóki ich nie unieważnisz, i można zmienić ich nazwy. Użyj opcji Przytrzymaj, aby unieważnić (naciśnij i przytrzymaj), aby natychmiast unieważnić token; unieważnione tokeny pozostają na liście do celów audytu.Tokeny dostępu OAuth 2.0: Obsługują PKCE (
S256), Dynamic Client Registration (/oauth/register), Client ID Metadata Documents (CIMD), unieważnianie tokenów (/oauth/revoke) oraz metadane wykrywania pod adresamihttps://api.userjot.com/.well-known/oauth-authorization-serverihttps://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. Tokeny dostępu są ważne przez 1 godzinę, a rotowane tokeny odświeżania — przez 30 dni (zakresyworkspaceioffline_access). Zachowują ważność tylko wtedy, gdy autoryzujący użytkownik nadal jest właścicielem lub administratorem tego obszaru roboczego.
Pierwsze żądanie
curl https://api.userjot.com/v1/boards \
-H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"Limity żądań
Żądania API i MCP korzystają ze wspólnego limitu dla obszaru roboczego:
Plan | Na minutę | Na godzinę |
|---|---|---|
Free | 10 żądań | 150 żądań |
Starter | 60 żądań | 1500 żądań |
Professional | 120 żądań | 5000 żądań |
Obowiązują też dodatkowe limity dla poszczególnych operacji:
Zasoby: Import zasobów, przesyłanie wieloczęściowe i automatyczny import obrazów Markdown korzystają ze wspólnego, osobnego limitu dla obszaru roboczego: 20 zapytań na minutę i 300 na godzinę (dodatkowo 20 na minutę i 300 na godzinę w przypadku finalizacji przesyłania).
Wiadomości wychodzące (
POST /v1/conversations): Dostępne tylko w płatnych planach; limit wynosi 5 dziennie w planie Starter i 15 dziennie w planie Professional (w planie Free zwracany jest kod409 plan_feature_unavailable).
Po przekroczeniu limitu API zwraca kod HTTP 429 wraz z nagłówkiem Retry-After i error.details.retry_after_seconds.
Stronicowanie, błędy i idempotencja
Stronicowanie za pomocą kursora. Punkty końcowe list akceptują
cursorilimit(maksymalnie100; wartości domyślne różnią się w zależności od punktu końcowego, na przykład10w przypadku rozbudowanych list, takich jak/v1/requestsi/v1/changelogs), a do przechodzenia dalej zwracająnext_cursor.Format błędów. Odpowiedzi z błędami zwracają
{ "error": { "code", "message", "details" } }i w każdej odpowiedzi zawierają nagłówekX-Request-Id. Typowe kody to422 validation_error(wraz zdetails.issues),409 plan_limit_reached,409 plan_feature_unavailable,409 request_merged,410 member_erased(w przypadkuGET/PATCH /v1/members/{member_id}poDELETE /v1/members/{member_id}usunięciu danych zgodnie z RODO),409 member_erased(w endpointach odwołujących się do usuniętego członka),409 help_slug_takeni409 help_version_conflict.Idempotencja. Dodaj nagłówek
Idempotency-Key(przechowywany przez 24 godziny wraz z odciskiem treści żądania), aby bezpiecznie ponawiać żądania tworzące zasoby w ośmiu endpointach:/v1/requests,/v1/changelogs,/v1/conversations,/v1/conversations/{conversation_id}/replies,/v1/conversations/{conversation_id}/notes,/v1/assets/import,/v1/help/articlesi/v1/help/collections.
Zasoby i obrazy
Obrazy (PNG, JPEG, GIF lub WebP o rozmiarze do 10 MiB) można przesyłać na trzy sposoby:
Przesyłanie wieloczęściowe:
POST /v1/assets(createAsset, tylko REST) przesyła obraz w jednym żądaniumultipart/form-data.Import z adresu URL:
POST /v1/assets/importpobiera publicznie dostępny obraz HTTPS do pamięci obszaru roboczego.Przesyłanie z podpisanym adresem URL w trzech krokach:
POST /v1/assets/uploads(podaj dokładnesize_bytes; maksymalnie 100 otwartych sesji przesyłania na obszar roboczy) → prześlij bajtyPUTna podpisany adres URL ważny przez 30 minut →POST /v1/assets/uploads/{upload_id}/complete.
Odwołuj się do przesłanych zasobów w Markdown za pomocą asset:<id>. Publiczne adresy URL obrazów HTTPS osadzone w Markdown przesyłanym do endpointów dziennika zmian i artykułów pomocy są również importowane automatycznie (maksymalnie 10 obrazów w treści na jedno żądanie dziennika zmian i 20 na jedno żądanie artykułu centrum pomocy). Są one uwzględniane w limicie zasobów obszaru roboczego.
Webhooki
Wychodzące webhooki dla klientów nie są jeszcze dostępne. Aby otrzymywać alerty zespołu w czasie rzeczywistym, użyj Connect Slack lub Connect Discord albo sprawdzaj zmiany za pomocą REST API.
REST czy MCP
Serwer MCP jest oparty na tym API i udostępnia 98 ze 100 operacji REST jako narzędzia MCP (POST /v1/assets przesyłanie wieloczęściowe i DELETE /v1/members/{member_id} usuwanie danych zgodnie z RODO są dostępne tylko przez REST). Korzystaj z REST API we własnym zapleczu, automatyzacji lub kodzie aplikacji, gdy chcesz mieć pełną kontrolę nad żądaniami i odpowiedziami. Korzystaj z MCP, gdy łączysz się z klientem AI obsługującym Model Context Protocol.
Zarządzanie tokenami
Traktuj token API jak każdy inny sekret:
Nie umieszczaj go na stałe w plikach konfiguracyjnych dodawanych do repozytorium.
W miarę możliwości używaj zmiennych środowiskowych lub menedżera sekretów.
W miarę możliwości używaj osobnych tokenów dla różnych środowisk lub członków zespołu.
Unieważniaj niepotrzebne już tokeny w sekcji Ustawienia → MCP & API, korzystając z opcji Przytrzymaj, aby unieważnić.