API-Überblick

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

Authentifizierung

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

Jeder Key ist auf einen Workspace beschränkt und kann auf derselben Einstellungsseite widerrufen werden, falls er kompromittiert wird.

Vergeben Sie nur die benötigten Scopes, etwa tickets:read, tickets:write oder comments:write. 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 (z. B. req_a1b2c3). Nennen Sie diesen Wert bei einer Fehlermeldung, damit verfolgen wir Ihre konkrete Anfrage in unseren Logs.

Statuscodes

• 400, fehlerhaftes JSON
• 401, fehlender oder ungültiger API-Key
• 402, das enthaltene API-Kontingent oder das konfigurierte Monatslimit ist erreicht
• 403, authentifiziert, aber nicht berechtigt (falsche Rolle, falscher Workspace)
• 404, Ressource existiert nicht (oder Sie dürfen sie nicht sehen)
• 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 wiederholbaren Erstellungs- und Änderungsanfragen einen stabilen Idempotency-Key-Header. Dieselbe Operation mit demselben Key liefert das gespeicherte Ergebnis, statt die Änderung doppelt auszuführen. 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 → Abrechnung 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.