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
Die REST-API zählt je Minute in drei Töpfen:
| Topf | Grenze pro Minute |
|---|---|
| je Nutzer, alle Pfade zusammen | 100 Requests |
| je Nutzer und Pfad | 30 Requests |
| je Pfad, über alle Aufrufer zusammen | 50 Requests |
„Pfad“ ist der konkrete Pfad samt IDs — /v1/lists/A und /v1/lists/B zählen getrennt. Ohne gültige Anmeldung zählt die IP-Adresse statt des Nutzers.
Jede Antwort trägt den Stand in Headern: X-RateLimit-UserLimit, X-RateLimit-UserRemaining, X-RateLimit-UserReset, dasselbe als X-RateLimit-UserPath* und X-RateLimit-Path*. Ein Topf, zu dem kein Header kommt, gilt nicht. Bei Überschreitung antwortet die API mit 429 und Retry-After (Sekunden, bis der erschöpfte Topf wieder frei ist).
Der MCP-Endpunkt /api/mcp zählt davon getrennt mit einem eigenen Limit (240/min je Nutzer) — siehe Rate Limits & Fehler.
Methoden-Semantik
GET— lesenPOST— anlegenPATCH— teilweise aktualisieren (nur gesendete Felder ändern sich)DELETE— löschen (bei Lists/Items: Soft-Delete → Papierkorb)