Dokumente

Endpunkte zum Auflisten, Abrufen, Herunterladen, Hochladen und Löschen von Dokumenten in Paperarchive. Mit Pagination, Filtern, Multipart-Upload und Rate Limits.

GET https://api.paperarchive.io/v1/documents

Scope:documents:read

Dokumente mit Paginierung und optionalen Filtern auflisten. Ergebnisse sind auf Spaces beschränkt, die für deinen API-Schlüssel zugänglich sind.

Query parameters

Name	Type	Required	Description
`limit`	integer	optional	Anzahl der zurückgegebenen Dokumente (1-100). Default: `50`
`offset`	integer	optional	Anzahl der zu überspringenden Dokumente für Paginierung. Default: `0`
`sort_by`	string	optional	Feld zum Sortieren. Default: `created_at` Values: `created_at, updated_at, title, document_date`
`sort_order`	string	optional	Sortierrichtung. Default: `desc` Values: `asc, desc`
`space_id`	uuid	optional	Nach Space-ID filtern.
`category_id`	uuid	optional	Nach Kategorie-ID filtern.
`status`	string	optional	Nach Dokumentenstatus filtern. Values: `pending, processing, completed, failed`
`created_after`	string (ISO 8601)	optional	Dokumente filtern, die nach diesem Zeitpunkt erstellt wurden (z.B. "2026-03-30T10:00:00Z"). Nuetzlich fuer inkrementelle Synchronisierung.

Code examples

curl -X GET "https://api.paperarchive.io/v1/documents?limit=10&sort_by=created_at" \
  -H "Authorization: Bearer pa_live_abc123def456"

GET https://api.paperarchive.io/v1/document/:id/download

Scope:documents:read

Originaldatei eines Dokuments per ID herunterladen. Gibt einen binären Dateistream mit Content-Disposition-Attachment-Header zurück. Alias: /v1/documents/:id/download. Erfordert Zugriff auf den Space des Dokuments.

Path parameters

Name	Type	Required	Description
`id`	uuid	required	Die Dokument-ID.

Code examples

curl -L "https://api.paperarchive.io/v1/document/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download" \
  -H "Authorization: Bearer pa_live_abc123def456" \
  -o document.pdf

GET https://api.paperarchive.io/v1/documents/:id

Scope:documents:read

Ein einzelnes Dokument per ID abrufen, einschließlich OCR-Text und KI-generierter Zusammenfassung. Nur zugänglich, wenn sich das Dokument in einem Space befindet, auf den dein API-Schlüssel Zugriff hat.

Path parameters

Name	Type	Required	Description
`id`	uuid	required	Die Dokument-ID.

Code examples

curl -X GET "https://api.paperarchive.io/v1/documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer pa_live_abc123def456"

POST https://api.paperarchive.io/v1/documents

Scope:documents:write

Eine Dokumentdatei (PDF oder Bild) hochladen. Die Datei wird sicher gespeichert und automatisch durch die OCR-/KI-Pipeline verarbeitet - Textextraktion, Metadatenanalyse, Kategorisierung und Embeddings erfolgen vollautomatisch. Als multipart/form-data senden. Der Dateiinhalt wird serverseitig per Magic-Byte-Signatur validiert. Der Ziel-Space wird immer auf Schreibzugriff geprüft. Auf 10 Uploads pro Minute begrenzt. Du kannst optional einen metadata-JSON-String mitschicken, um Dokumenteigenschaften vorab zu setzen. Deine Metadaten haben Vorrang vor KI-extrahierten Werten - die KI läuft trotzdem, um Lücken zu füllen.

Request body

Name	Type	Required	Description
`file`	file	required	PDF-, JPEG-, PNG- oder TIFF-Datei. Maximal 50 MB. Der Inhalt wird per Magic Bytes validiert - der Content-Type-Header muss zum tatsächlichen Dateiinhalt passen.
`space_id`	uuid	optional	Ziel-Space. Fällt auf deinen Standard-Space zurück, wenn nicht angegeben. API-Schlüssel, die auf bestimmte Spaces beschränkt sind, können nur in diese Spaces hochladen.
`metadata`	JSON string	optional	Optionaler JSON-String mit eigenen Metadaten, um Dokumenteigenschaften vorab zu setzen. Deine Werte haben Vorrang vor der KI-Extraktion. Unterstützte Felder: event_type (invoice, receipt, contract, policy, notice, payslip, letter, statement, offer, credit_note), state_hint (open, paid, active, expired), amount ({ value: number, currency: string }), sender_name (string), document_date (YYYY-MM-DD oder ISO 8601), due_date (YYYY-MM-DD), paid_at (YYYY-MM-DD - markiert das Dokument als bezahlt und erstellt einen bestätigten Zahlungseintrag), reference_number (string), tags (String-Array, max. 5), category (string - Kategoriename), title (string - Dokumenttitel-Überschreibung). Wenn paid_at angegeben wird, wird das Event direkt im Status "paid" erstellt mit einem bestätigten Zahlungseintrag - keine manuelle Bestätigung nötig. Das ist nützlich, wenn dein System den Zahlungsstatus bereits kennt.

Code examples

# Einfacher Upload
curl -X POST "https://api.paperarchive.io/v1/documents" \
  -H "Authorization: Bearer pa_live_abc123def456" \
  -F "[email protected]" \
  -F "space_id=space-uuid-here"

# Upload mit eigenen Metadaten (Dokumenteigenschaften vorab setzen)
curl -X POST "https://api.paperarchive.io/v1/documents" \
  -H "Authorization: Bearer pa_live_abc123def456" \
  -F "[email protected]" \
  -F "space_id=space-uuid-here" \
  -F 'metadata={"event_type":"invoice","sender_name":"Cloudflare Inc.","amount":{"value":199.99,"currency":"EUR"},"reference_number":"INV-2026-042"}'

# Eine bezahlte Rechnung hochladen (überspringt den Prüf-Workflow)
curl -X POST "https://api.paperarchive.io/v1/documents" \
  -H "Authorization: Bearer pa_live_abc123def456" \
  -F "[email protected]" \
  -F 'metadata={"event_type":"invoice","amount":{"value":199.99,"currency":"EUR"},"paid_at":"2026-03-10","sender_name":"Cloudflare Inc."}'

DELETE https://api.paperarchive.io/v1/documents/:id

Scope:documents:write

Ein Dokument soft-löschen. Das Dokument wird als gelöscht markiert, kann aber wiederhergestellt werden. Funktioniert nur für Dokumente in Spaces, die für deinen API-Schlüssel zugänglich sind.

Path parameters

Name	Type	Required	Description
`id`	uuid	required	Die zu löschende Dokument-ID.

Code examples

curl -X DELETE "https://api.paperarchive.io/v1/documents/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer pa_live_abc123def456"