REST API

Shayan TaslimAktualisiert

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

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

UserJot 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 unter https://api.userjot.com/.well-known/oauth-authorization-server und https://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- und offline_access-Scopes). Beide bleiben nur gültig, solange der autorisierende Benutzer Inhaber oder Admin des Arbeitsbereichs ist.

Eine erste Anfrage

Bash
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 wird 409 plan_feature_unavailable zurü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 cursor und limit (bis zu 100; Standardwerte variieren je nach Endpunkt, beispielsweise 10 bei umfangreichen Listen wie /v1/requests und /v1/changelogs) und geben next_cursor zurück, um die nächste Seite abzurufen.

  • Fehlerformat. Fehlerantworten geben { "error": { "code", "message", "details" } } zurück und enthalten in jeder Antwort den Response-Header X-Request-Id. Häufige Codes sind 422 validation_error (mit details.issues), 409 plan_limit_reached, 409 plan_feature_unavailable, 409 request_merged, 410 member_erased (bei GET/PATCH /v1/members/{member_id} nach der DSGVO-Löschung über DELETE /v1/members/{member_id}), 409 member_erased (bei Routen, die auf ein gelöschtes Mitglied verweisen), 409 help_slug_taken und 409 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/articles und /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 einzelnen multipart/form-data-Anfrage hoch.

  • Import über URL: POST /v1/assets/import lädt ein öffentliches HTTPS-Bild in den Speicher des Arbeitsbereichs herunter.

  • Upload mit vorab signierter URL in drei Schritten: POST /v1/assets/uploads (mit exaktem size_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.

Hat das Ihre Frage beantwortet?