Konventionen

Format

• Requests & Responses: application/json.
• IDs: UUID oder SID (Kurz-ID) werden bei den meisten Ressourcen akzeptiert.
• Zeitstempel: ISO 8601 (UTC).

Authentifizierung

Bearer-Token im Authorization-Header. Ohne gültigen Token → 401.

Pagination

Listen-Endpunkte nehmen page und pageSize entgegen (nicht limit/offset) und liefern einen Envelope mit pagination-Objekt:

Query	Typ	Default	Beschreibung
page	number ≥ 1	1	Seite
pageSize	number 1–100	20*	Einträge pro Seite
search	string	–	Freitextsuche (wo unterstützt)
sort	string	–	Sortierfeld (wo unterstützt)

* pageSize ist bei Lists und List Items standardmäßig 50.

{
  "data": [ … ],
  "pagination": { "total": 128, "page": 1, "pageSize": 50, "totalPages": 3 }
}

Für die nächste Seite page erhöhen, bis page >= totalPages.

Unterschied zum MCP

Der MCP-Server nutzt ein anderes Schema: limit/offset als Eingabe und { items, total, limit, offset, has_more } als Antwort. Die REST-API nutzt page/pageSize und den pagination-Envelope oben.

HTTP-Statuscodes

Code	Bedeutung
200	OK
201	Erstellt
400	Ungültige Anfrage (Validierung)
401	Nicht authentifiziert
403	Keine Berechtigung
404	Nicht gefunden
429	Rate-Limit überschritten (siehe unten)

Rate Limiting

Wie beim MCP-Endpunkt: 240 Requests/Minute pro Token. Bei Überschreitung 429 mit Retry-After-Header.

Methoden-Semantik

• GET — lesen
• POST — anlegen
• PATCH — teilweise aktualisieren (nur gesendete Felder ändern sich)
• DELETE — löschen (bei Lists/Items: Soft-Delete → Papierkorb)