REST API
Die UserJot REST API stellt Ihrem Code dieselben Arbeitsbereichsdaten bereit, die auch das Dashboard verwendet: Metadaten des Arbeitsbereichs, Boards, Anfragen (einschließlich Zusammenführungen, ähnlicher Anfragen, Tags, Abonnements und Anhänge), Kommentare, Stimmen, Changelog-Einträge, Mitglieder (einschließlich der Löschung gemäß DSGVO), Unternehmen, Konversationen, Assets sowie Sammlungen und Artikel im Help Center.
Die vollständige interaktive Referenz mit allen Routen, Schemas und Beispielen finden Sie unter userjot.com/docs/api und direkt unter https://api.userjot.com/v1/docs. Das zugrunde liegende OpenAPI-Dokument ist unter https://api.userjot.com/v1/openapi.json verfügbar (und wird auch unter https://userjot.com/docs/api/openapi.json gespiegelt), damit Sie typisierte Clients in Ihrer Programmiersprache generieren können.
Basis-URL und Authentifizierung
Base URL: https://api.userjot.com/v1
Authorization: Bearer YOUR_USERJOT_API_TOKENUserJot akzeptiert auf /v1/*-Routen zwei Arten von Bearer-Tokens:
API-Tokens: Erstellen Sie ein Token unter Einstellungen → MCP & API (nur für Admins und Inhaber). Tokens haben das Präfix
uj_live_, gehören zu einem Arbeitsbereich, laufen erst ab, wenn sie widerrufen werden, und können umbenannt werden. Verwenden Sie Zum Widerrufen gedrückt halten (gedrückt halten), um ein Token sofort zu widerrufen. Widerrufene Tokens bleiben aus Gründen der Auditierbarkeit aufgeführt.OAuth 2.0-Zugriffstokens: Unterstützt PKCE (
S256), Dynamic Client Registration (/oauth/register), Client ID Metadata Documents (CIMD), Token-Widerruf (/oauth/revoke) sowie Erkennungsmetadaten unterhttps://api.userjot.com/.well-known/oauth-authorization-serverundhttps://api.userjot.com/.well-known/oauth-protected-resource/v1/mcp. Zugriffstokens sind 1 Stunde gültig. Rotierende Refresh-Tokens sind 30 Tage gültig (workspace- undoffline_access-Scopes). Beide bleiben nur gültig, solange der autorisierende Benutzer Inhaber oder Admin des Arbeitsbereichs ist.
Eine erste Anfrage
curl https://api.userjot.com/v1/boards \
-H "Authorization: Bearer YOUR_USERJOT_API_TOKEN"Ratenbegrenzungen
API- und MCP-Anfragen teilen sich das Ratenlimit-Budget eines Workspaces:
Tarif | Pro Minute | Pro Stunde |
|---|---|---|
Free | 10 Anfragen | 150 Anfragen |
Starter | 60 Anfragen | 1.500 Anfragen |
Professional | 120 Anfragen | 5.000 Anfragen |
Zusätzlich gelten budgetspezifische Limits für einzelne Vorgänge:
Assets: Asset-Imports, Multipart-Uploads und automatisch importierte Markdown-Bilder teilen sich ein separates Kontingent von 20 Anfragen pro Minute und 300 pro Stunde je Arbeitsbereich (zuzüglich 20 pro Minute und 300 pro Stunde für den Abschluss des Uploads).
Ausgehende Konversationen (
POST /v1/conversations): Nur in kostenpflichtigen Tarifen verfügbar; begrenzt auf 5 pro Tag bei Starter und 15 pro Tag bei Professional (bei Free wird409 plan_feature_unavailablezurückgegeben).
Bei Überschreitung eines Limits gibt die API den HTTP-Status 429 mit einem Retry-After-Header und error.details.retry_after_seconds zurück.
Paginierung, Fehler und Idempotenz
Cursor-Paginierung. Listen-Endpunkte akzeptieren
cursorundlimit(bis zu100; Standardwerte variieren je nach Endpunkt, beispielsweise10bei umfangreichen Listen wie/v1/requestsund/v1/changelogs) und gebennext_cursorzurück, um die nächste Seite abzurufen.Fehlerformat. Fehlerantworten geben
{ "error": { "code", "message", "details" } }zurück und enthalten in jeder Antwort den Response-HeaderX-Request-Id. Häufige Codes sind422 validation_error(mitdetails.issues),409 plan_limit_reached,409 plan_feature_unavailable,409 request_merged,410 member_erased(beiGET/PATCH /v1/members/{member_id}nach der DSGVO-Löschung überDELETE /v1/members/{member_id}),409 member_erased(bei Routen, die auf ein gelöschtes Mitglied verweisen),409 help_slug_takenund409 help_version_conflict.Idempotenz. Senden Sie einen
Idempotency-Key-Header (wird 24 Stunden lang zusammen mit einem Fingerabdruck des Anfrageinhalts gespeichert), um Erstellungsanfragen auf acht Routen sicher zu wiederholen:/v1/requests,/v1/changelogs,/v1/conversations,/v1/conversations/{conversation_id}/replies,/v1/conversations/{conversation_id}/notes,/v1/assets/import,/v1/help/articlesund/v1/help/collections.
Assets und Bilder
Laden Sie Bilder (PNG, JPEG, GIF oder WebP bis zu 10 MiB) auf drei Arten hoch:
Multipart-Upload:
POST /v1/assets(createAsset, nur REST) lädt ein Bild in einer einzelnenmultipart/form-data-Anfrage hoch.Import über URL:
POST /v1/assets/importlädt ein öffentliches HTTPS-Bild in den Speicher des Arbeitsbereichs herunter.Upload mit vorab signierter URL in drei Schritten:
POST /v1/assets/uploads(mit exaktemsize_bytes; bis zu 100 offene Upload-Sitzungen pro Arbeitsbereich) →PUT-Bytes an die 30 Minuten gültige, vorab signierte URL →POST /v1/assets/uploads/{upload_id}/complete.
Verweisen Sie in Markdown mit asset:<id> auf hochgeladene Assets. Öffentliche HTTPS-Bild-URLs, die in Markdown an Changelog- und Help-Artikel-Endpunkte übermittelt werden, werden ebenfalls automatisch importiert (bis zu 10 Inline-Bilder pro Changelog-Anfrage und 20 pro Help-Center-Artikelanfrage). Sie werden auf das Asset-Kontingent des Arbeitsbereichs angerechnet.
Webhooks
Ausgehende Webhooks für Kunden sind derzeit noch nicht verfügbar. Für Team-Benachrichtigungen in Echtzeit können Sie Connect Slack oder Connect Discord verwenden oder Änderungen über die REST API abfragen.
REST oder MCP
Der MCP-Server basiert auf dieser API und stellt 98 der 100 REST-Vorgänge als MCP-Tools bereit (POST /v1/assets Multipart-Upload und DELETE /v1/members/{member_id} DSGVO-Löschung sind nur über REST verfügbar). Verwenden Sie die REST API in Ihrem eigenen Backend, in Automatisierungen oder im Anwendungscode, wenn Sie die volle Kontrolle über Anfragen und Antworten benötigen. Verwenden Sie MCP, wenn Sie einen KI-Client anbinden, der das Model Context Protocol unterstützt.
Umgang mit Tokens
Behandle dein API-Token wie jedes andere Geheimnis:
Fügen Sie es nicht fest in versionierte Konfigurationsdateien ein.
Verwenden Sie nach Möglichkeit Umgebungsvariablen oder einen Secrets-Manager.
Verwenden Sie nach Möglichkeit separate Tokens für verschiedene Umgebungen oder Teammitglieder.
Widerrufen Sie nicht mehr benötigte Tokens unter Einstellungen → MCP & API, indem Sie Zum Widerrufen gedrückt halten verwenden.