Kategorien

Endpunkte zum Auflisten, Erstellen und Löschen von Kategorien in Paperarchive. Kategorien gehören einem Nutzer; die Space-Zuordnung läuft über category_spaces.

GET https://api.paperarchive.io/v1/categories
Scope:categories:read

Listet deine Kategorien auf, die mit mindestens einem zugänglichen Space verknüpft sind (legacy categories.space_id oder category_spaces). Jedes Objekt enthält membership_space_ids.

Code examples

curl -X GET "https://api.paperarchive.io/v1/categories" \
  -H "Authorization: Bearer pa_live_abc123def456"
POST https://api.paperarchive.io/v1/categories
Scope:categories:write

Neue Kategorie anlegen und einem Space zuordnen. Fehlt space_id, wird der Standard-Space des Kontos genutzt (falls vorhanden).

Request body

NameTypeRequiredDescription
namestring required Kategoriename.
space_iduuid optional Ziel-Space für die erste Zuordnung. Weglassen = Standard-Space.
colorstring optional Hex-Farbcode (z.B. "#ef4444").
iconstring optional Icon-Name.

Code examples

curl -X POST "https://api.paperarchive.io/v1/categories" \
  -H "Authorization: Bearer pa_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{"name": "Receipts", "space_id": "space-uuid-1", "color": "#f59e0b"}'
DELETE https://api.paperarchive.io/v1/categories/:id
Scope:categories:write

Eine Kategorie löschen. Nur möglich, wenn die Kategorie mit mindestens einem Space verknüpft ist, den dein API-Schlüssel abdeckt (category_spaces oder legacy space_id).

Path parameters

NameTypeRequiredDescription
iduuid required Die zu löschende Kategorie-ID.

Code examples

curl -X DELETE "https://api.paperarchive.io/v1/categories/cat-uuid-1" \
  -H "Authorization: Bearer pa_live_abc123def456"

Smoke-Test-Checkliste (Kategorien-API)

Nutze einen Test-API-Schlüssel mit categories:read und categories:write (und spaces:read, damit du Space-UUIDs ermitteln kannst). Führe die Schritte gegen Staging oder lokale API aus.

  1. GET /v1/categories - Erwartung: 200, success: true, data als Array. Jedes Objekt hat membership_space_ids (Array, bei Legacy-Zeilen vor Backfill ggf. leer).
  2. POST mit space_id - POST /v1/categories mit Body {"name":"API Smoke Cat","space_id":"<uuid>"}. Erwartung: 201, in der Antwort enthält membership_space_ids diesen Space.
  3. POST ohne space_id - Nur {"name":"API Smoke Cat Default"}. Erwartung: 201, wenn ein Standard-Space existiert, sonst 400 mit verständlicher Fehlermeldung.
  4. GET erneut - Neue Kategorie erscheint; membership_space_ids entspricht dem genutzten (oder Standard-)Space.
  5. DELETE - DELETE /v1/categories/<id> mit der neuen ID. Erwartung: 200, success: true. GET wiederholen: Kategorie weg.
  6. Eingeschränkter API-Schlüssel - Schlüssel nur für einen Space: POST mit space_id außerhalb des Schlüssels - Erwartung: 403.