Request and response format

Every REST endpoint lives under https://stage-api.paperpile.com/v1. The system and protocol endpoints are the exception: they sit at the root of their hosts, and each one lists its own server.

Requests

Send request bodies as JSON with Content-Type: application/json. Uploading a file is the one exception: it takes multipart/form-data, with the file in the file part.

PATCH updates are partial. Send only the fields you want to change, and at least one of them.

A query parameter that accepts several values is repeated: ?reference_ids=ID1&reference_ids=ID2.

Responses

Successful responses are JSON, apart from the two downloads: GET /files/{file_id}/content returns the file's bytes, and GET /files/bulk returns a .tar.gz archive.

Request	Status	Body
GET	200	The resource, or a list
POST that creates something	201	The new resource
PATCH	200	The updated resource
DELETE	204	Empty

The exceptions: bulk updates and deletes answer 200 with { "succeeded": <count> }; adding references to a folder or a label answers 204; and POST /references/save, POST /catalog/lookup, and highlighting answer 200. Each operation lists its exact responses.

Lists come in an envelope:

{ "data": [], "total": 0, "cursor": null }

cursor is null unless more results remain; see Pagination. GET /libraries and GET /folders/{folder_id}/folders return a bare array instead.

Identifiers and timestamps

IDs are opaque strings. The personal library's ID is always personal. Timestamps such as created_at are Unix timestamps in seconds.