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). Paperarchive prüft den Namen vorher gegen deine bestehenden Kategorien: Gibt es eine Hauptkategorie mit gleichem Namen (ohne Rücksicht auf Groß-/Kleinschreibung und Leerzeichen am Rand), kommt sie mit Status 200 zurück, statt eine Dublette anzulegen. Gibt es ähnliche Kategorien (andere Schreibweise wie "&" und "und", Einzahl/Mehrzahl, Synonyme wie "Kfz"/"Auto" oder ineinander steckende Namen), antwortet die API mit 409, Fehler "similar_exists" und den Kandidaten; mit force: true legst du die Kategorie trotzdem an. Eine neue Kategorie liefert 201.

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.
forceboolean optional Kategorie auch dann anlegen, wenn ähnliche Kategorien existieren (überspringt die Antwort 409 similar_exists). Ein exakt gleicher Name liefert weiterhin die bestehende Kategorie.

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, die du angelegt hast, in den Papierkorb verschieben (Soft-Delete). 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). Nur wer die Kategorie angelegt hat, kann sie löschen; in der App lässt sie sich 30 Tage lang wiederherstellen, ihre Dokumente behalten die Zuordnung.

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. POST mit demselben Namen - Erwartung: 200 und dieselbe id (keine Dublette).
  6. POST mit ähnlichem Namen - z.B. die Mehrzahl des Namens. Erwartung: 409 mit error: "similar_exists" und candidates; mit "force": true Erwartung 201.
  7. DELETE - DELETE /v1/categories/<id> mit der neuen ID. Erwartung: 200, success: true. GET wiederholen: Kategorie weg (sie liegt im Papierkorb).
  8. Eingeschränkter API-Schlüssel - Schlüssel nur für einen Space: POST mit space_id außerhalb des Schlüssels - Erwartung: 403.