REST API

Shayan TaslimZaktualizowano

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

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

UserJot 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 adresami https://api.userjot.com/.well-known/oauth-authorization-server i https://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 (zakresy workspace i offline_access). Zachowują ważność tylko wtedy, gdy autoryzujący użytkownik nadal jest właścicielem lub administratorem tego obszaru roboczego.

Pierwsze żądanie

Bash
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 kod 409 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ą cursor i limit (maksymalnie 100; wartości domyślne różnią się w zależności od punktu końcowego, na przykład 10 w przypadku rozbudowanych list, takich jak /v1/requests i /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łówek X-Request-Id. Typowe kody to 422 validation_error (wraz z details.issues), 409 plan_limit_reached, 409 plan_feature_unavailable, 409 request_merged, 410 member_erased (w przypadku GET/PATCH /v1/members/{member_id} po DELETE /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_taken i 409 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/articles i /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 żądaniu multipart/form-data.

  • Import z adresu URL: POST /v1/assets/import pobiera 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ładne size_bytes; maksymalnie 100 otwartych sesji przesyłania na obszar roboczy) → prześlij bajty PUT na 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ć.

Czy ten artykuł odpowiedział na Twoje pytanie?