Grundlagen

API-Key im Header X-API-Key (oder Authorization: Bearer <key>). Keys entstehen in der App unter Einstellungen → Integrationen → API Keys. Live-Keys beginnen mit kv_live_, Test-Keys mit kv_test_. Den Key nie in der URL übergeben und nie im Browser einsetzen.

Jeder Key gehört zu einem Konto und handelt mit den Rechten der Person, die ihn angelegt hat. Was ein Key zusätzlich darf, legen seine Berechtigungen fest (siehe unten).

Mit einem Test-Key liefern lesende Aufrufe echte Daten. Schreibende, löschende und nach außen wirkende Aufrufe werden vollständig geprüft, aber nur simuliert (meta.test_mode: true).

Immer { ok, data, meta } bzw. bei Fehlern { ok: false, error: { code, message, details } }. meta.request_id bitte bei Support-Anfragen nennen.

{
  "ok": true,
  "data": [
    {
      "id": "5b0c1e7a-3f1d-4a52-9c1e-8a7d2b6f4e10",
      "first_name": "Anna"
    }
  ],
  "meta": {
    "request_id": "req_2b81d0aa",
    "next_cursor": "eyJvIjoyNX0"
  }
}

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Die Anfrage enthält ungültige Felder. Details stehen in error.details.",
    "details": [
      {
        "field": "email",
        "message": "muss eine E-Mail-Adresse sein"
      }
    ]
  },
  "meta": {
    "request_id": "req_7f3a9c1e"
  }
}

Listen liefern höchstens limit Einträge (Standard 25, max. 100). Gibt es mehr, steht in meta.next_cursor der Wert für ?cursor=.

120 Anfragen pro Minute und 3000 pro Stunde je Key, Body höchstens 1 MB. Bei Überschreitung 429 mit Header Retry-After.

Die API ist ab dem Growth-Tarif mit aktivem Abo enthalten.

Der HTTP-Status zeigt die Art des Fehlers, error.code den genauen Grund. error.details nennt bei Prüffehlern jedes betroffene Feld.

Jeder API-Key hat eine Liste von Berechtigungen (Scopes). Ein Endpunkt nennt bei sich, welchen Scope er braucht und welches Recht die Person in der App haben muss, die den Key angelegt hat. Sensible Scopes werden nie automatisch vergeben.