API-Überblick

REST, JSON, Authentifizierung per API-Key. In jedem Tarif enthalten, auch im kostenlosen.

Authentifizierung

Ein Workspace in der App ist ein Projekt in der API; sein Slug ist der Parameter project.

Erzeugen Sie einen Key unter Einstellungen → API-Keys (Admin-Rolle erforderlich). Den Key-Wert sehen Sie genau einmal, kopieren Sie ihn an einen sicheren Ort, bevor Sie den Dialog schließen, denn wir können ihn nicht erneut anzeigen. Schicken Sie ihn mit jeder Anfrage als Bearer-Token mit:

curl -H "Authorization: Bearer ld_your_api_key_here" \
  https://api.fesk.io/v1/tickets

Der Header X-API-Key funktioniert ebenso; ein Key in der URL (?api_key=) wird mit 400 abgewiesen. Keys können auf einen Workspace beschränkt werden und ein Ablaufdatum haben, danach antworten sie mit 401. Einen kompromittierten Key können Sie auf derselben Einstellungsseite widerrufen.

Vergeben Sie nur die benötigten Scopes, etwa tickets:read, tickets:write oder comments:write. Ein Schreib-Scope schließt den Lese-Scope derselben Ressource ein (tickets:write liest auch Tickets, comments:write auch Kommentare), und * erlaubt alles. Am einfachsten ist ein projektgebundener Key. Ist ein Key keinem Projekt zugeordnet, müssen Ticket- und Board-Anfragen ein Projekt angeben, entweder eine numerische project_id oder einen lesbaren project-Slug (z. B. ?project=infrastructure); andernfalls antwortet die API mit 400.

Projekte ermitteln

Sie müssen die internen Projekt-IDs nicht kennen. Rufen Sie GET /v1/projects mit einem beliebigen gültigen Key auf, um die erreichbaren Projekte aufzulisten, jeweils mit einem stabilen slug, den Sie anstelle der numerischen ID verwenden können:

curl -H "Authorization: Bearer ld_your_api_key_here" \
  https://api.fesk.io/v1/projects

{
  "ok": true,
  "data": {
    "projects": [
      { "id": 3, "name": "Infrastructure", "slug": "infrastructure", "description": null }
    ],
    "count": 1
  }
}

Überall dort, wo ein Endpunkt ein Projekt benötigt, können Sie ?project=<slug> statt ?project_id=<id> übergeben. Ein projektgebundener Key löst das Projekt automatisch auf und benötigt keines von beiden.

Basis-URL

https://api.fesk.io/v1/

Externe Integrationen laufen über die api.-Subdomain mit einem /v1-Versionspräfix, zum Beispiel https://api.fesk.io/v1/tickets. API-Keys funktionieren nur auf dieser Subdomain; an die Hauptdomain gesendet ergeben sie 401.

Antwortformat

Jede Antwort verwendet denselben Umschlag, sodass ein einziger Client damit umgehen kann:

{
  "ok": true,
  "data": { }
}

Bei Fehlern ist ok false, und statt data enthält die Antwort ein error-Objekt:

{
  "ok": false,
  "error": {
    "code": 422,
    "message": "Validation failed",
    "validation_errors": { }
  }
}

Der X-Correlation-ID-Response-Header enthält eine Anfrage-Kennung, eine Hex-Zeichenfolge aus 32 Zeichen wie 81132ce3df94f6e6d855bb563299f637. Nennen Sie diesen Wert bei einer Fehlermeldung, damit verfolgen wir Ihre konkrete Anfrage in unseren Logs.

Statuscodes

• 400, fehlerhaftes JSON, kein Projekt angegeben oder der Key in der URL
• 401, fehlender, ungültiger oder abgelaufener API-Key
• 402, das enthaltene API-Kontingent oder das konfigurierte Monatslimit ist erreicht
• 403, authentifiziert, aber nicht berechtigt: dem Key fehlt der Scope, oder project_id nennt einen Workspace, den der Key nicht erreicht
• 404, Ressource existiert nicht oder liegt in einem anderen Workspace als dem der Anfrage
• 422, Validierung fehlgeschlagen; error.validation_errors enthält die feldbezogenen Meldungen
• 429, Rate-Limit erreicht; prüfen Sie den Retry-After-Header
• 5xx, Fehler auf unserer Seite; senden Sie uns den X-Correlation-ID-Header

Sichere Wiederholungen

Senden Sie bei jedem POST, bei PUT /v1/tickets/{id} und bei PATCH /v1/tickets/{id}/status einen stabilen Idempotency-Key-Header (1 bis 128 Zeichen), wenn die Anfrage wiederholt werden könnte. Dieselbe Anfrage mit demselben Key und denselben Daten liefert das gespeicherte erfolgreiche Ergebnis, statt die Änderung doppelt auszuführen. Andere Änderungen ignorieren den Header. Für eine tatsächlich neue Operation verwenden Sie einen neuen Key.

Rate-Limiting

Anfragen sind pro API-Key über ein Sliding-Window-Verfahren begrenzt. Bei Überschreitung erhalten Sie 429 mit einem Retry-After-Header. Warten Sie mindestens so lange; wiederholt anfragende Clients sollten exponentielles Backoff mit Jitter verwenden.

API-Aufrufe werden außerdem für die Abrechnung gezählt. Die ersten 5.000 Aufrufe pro Monat sind enthalten. Unter Einstellungen → Plan & Nutzung kann ein Admin bezahlte API-Nutzung aktivieren oder ein niedrigeres Monatslimit setzen; beim Erreichen antwortet die API mit 402 und nennt Grund und aktuelle Nutzung.

Häufig verwendete Endpunkte

Das ist nur ein Ausschnitt, für die vollständige Liste mit Request- und Response-Schemata siehe die interaktive API-Referenz.