ENPlattform

Überblick

Antworten und Fehler

Aufbau der Antworten, Seiten, Sperren gegen Überschreiben und Fehlercodes.

Alle Adressen unter /spaces/{space} antworten im selben Aufbau. Die Wissensdatenbank weicht davon noch ab, das steht weiter unten.

Einzelne Ressource

{
  "data": {
    "id": "0199a3c2-7d4e-7b21-9f3a-2c5e8d1b4a70",
    "name": "Empfang",
    "updated_at": "2026-09-21T10:15:00+02:00"
  }
}

Listen

Listen tragen neben data das Feld meta. Mit ?page= blätterst du, mit ?per_page= bestimmst du die Seitengröße (Standard 50, höchstens 200). Auf der letzten Seite ist next_page gleich null.

{
  "data": [
    "…"
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 132,
    "next_page": 2
  }
}

Schreiben

POST, PATCH und DELETE liefern die Ressource nach dem Schreiben in data. Bei Ressourcen, die erst veröffentlicht werden müssen, steht in sync der Stand der Veröffentlichung.

Bei PATCH ändern sich nur die Felder, die du mitschickst. Verschachtelte Objekte wie behavior.values oder das recipe eines Tools werden nach Schlüsseln zusammengeführt, Listen wie tool_ids werden vollständig ersetzt.

Schutz vor Überschreiben

Schicke bei PATCH und DELETE das Feld expected_updated_at mit, also updated_at aus deinem letzten Lesen. Hat inzwischen jemand anderes die Ressource geändert, lehnt die API ab, statt dessen Änderung stillschweigend zu überschreiben:

{
  "code": "stale",
  "message": "The record changed since you read it.",
  "current": {
    "…": "…"
  }
}

Lies dann current, führe deine Änderung darauf aus und schicke sie erneut.

Fehler

Fehler tragen immer code und message. Validierungsfehler nennen zusätzlich jedes ungültige Feld mit seinem Pfad:

{
  "code": "validation",
  "message": "1 field is invalid.",
  "errors": [
    {
      "path": "behavior.values.tone.closeness",
      "code": "invalid_enum",
      "message": "Must be one of formal, personal."
    }
  ]
}
Status code Bedeutung
400 invalid_json Der Body ist kein gültiges JSON.
401 unauthenticated Schlüssel fehlt, ist falsch oder gelöscht.
403 forbidden Der Schlüssel darf das in diesem Space nicht.
404 not_found Die Ressource gibt es in diesem Space nicht, oder die Adresse ist falsch.
405 method_not_allowed Die Adresse gibt es, aber nicht mit dieser Methode.
409 stale expected_updated_at passt nicht mehr. current enthält den aktuellen Stand.
409 referenced Löschen abgelehnt, weil noch etwas darauf verweist. references nennt, was.
422 validation Felder ungültig. errors nennt jedes Feld mit Pfad.
429 rate_limited Mehr als 60 Anfragen pro Minute. Retry-After beachten.
500 server_error Fehler bei uns. Mit X-Request-Id an den Support wenden.

Fehler eines Drittanbieters, etwa einer angebundenen Schnittstelle, kommen unverändert unter code: upstream mit Status und Meldung des Anbieters zurück.

Köpfe

Jede Antwort trägt X-RateLimit-Limit, X-RateLimit-Remaining und X-Request-Id. Die Request-ID hilft dem Support, einen Aufruf in unseren Protokollen zu finden.

Wissensdatenbank

Die Adressen unter /knowledge sind älter und folgen noch dem vorigen Aufbau: Listen tragen neben data die Felder links und meta, Fehler nur message. Jede Antwort zu einem Dokument oder Ordner enthält sync_status und sync_error. Dateien dürfen bis 20 MB groß sein.