Documents

Endpoints for listing, retrieving, downloading, creating, and deleting documents.

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

Scope:documents:read

List documents with pagination and optional filters. Results are scoped to spaces accessible by your API key.

Query parameters

Name	Type	Required	Description
`limit`	integer	optional	Number of documents to return (1-100). Default: `50`
`offset`	integer	optional	Number of documents to skip for pagination. Default: `0`
`sort_by`	string	optional	Field to sort by. Default: `created_at` Values: `created_at, updated_at, title, document_date`
`sort_order`	string	optional	Sort direction. Default: `desc` Values: `asc, desc`
`space_id`	uuid	optional	Filter by space ID.
`category_id`	uuid	optional	Filter by category ID.
`status`	string	optional	Filter by document status. Values: `pending, processing, completed, failed, skipped`
`created_after`	string (ISO 8601)	optional	Filter documents created after this timestamp (e.g. "2026-03-30T10:00:00Z"). Useful for incremental syncs.

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

Download the original file for a document by ID. Returns a binary file stream with Content-Disposition attachment header. Alias: /v1/documents/:id/download. Requires access to the document space.

Path parameters

Name	Type	Required	Description
`id`	uuid	required	The document 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

Retrieve a single document by ID, including OCR text and AI-generated summary. Only accessible if the document is in a space your API key can access.

Path parameters

Name	Type	Required	Description
`id`	uuid	required	The document 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

Upload a document file (PDF or image). The file is stored securely and automatically processed through the OCR / AI pipeline - text extraction, metadata analysis, categorization, and embeddings all happen automatically. Send as multipart/form-data. File content is validated server-side via magic-byte signatures. The resolved target space is always checked for write access. Rate-limited to 10 uploads per minute. You can optionally pass a metadata JSON string to pre-populate document properties. Metadata you provide takes precedence over AI-extracted values - the AI still runs to fill in any gaps.

Request body

Name	Type	Required	Description
`file`	file	required	PDF, JPEG, PNG, or TIFF file. Max 50 MB. Content is validated by magic bytes - the Content-Type header must match the actual file content.
`space_id`	uuid	optional	Target space. Falls back to your default space if omitted. API keys restricted to specific spaces can only upload to those spaces.
`metadata`	JSON string	optional	Optional JSON string with custom metadata to pre-populate on the document. Your values take precedence over AI extraction. Supported fields: 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 or ISO 8601), due_date (YYYY-MM-DD), paid_at (YYYY-MM-DD - marks the document as paid and creates a confirmed payment record), reference_number (string), tags (string array, max 5), category (string - category name), title (string - document title override). When paid_at is provided, the event is created directly in the "paid" state with a confirmed payment record - no manual confirmation needed. This is useful when your system already knows the payment status.

Code examples

# Basic 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 with custom metadata (pre-populate document properties)
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"}'

# Upload a paid invoice (skips the review flow entirely)
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

Soft-delete a document. The document is marked as deleted but can be recovered. Only works for documents in spaces accessible by your API key.

Path parameters

Name	Type	Required	Description
`id`	uuid	required	The document ID to delete.

Code examples

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