Guides
Library documents
Upload files to the workspace library, read versions, render pages as PNG and preview or commit edits on an exact base version.
Library documents are the files in your workspace's cloud library — the same files people open in Account → Documents. Every change makes a new, immutable version, and every edit through the API is made on an exact base version: if someone saved first, the answer is 409 VERSION_CONFLICT and nothing is overwritten. Keys need the library:read scope to read and library:write to upload and edit. The cloud library must be turned on for the workspace.
/documents endpoints: those are agreements sent for signature. Library documents live under /library/.Upload a file#
Three steps: an upload session reserves the space, you send the bytes, then you confirm. PDF, JPEG, PNG and WebP files up to your plan's file size.
curl https://macaaw.com/public/v1/library/uploads \
-H "Authorization: API-Key $MACAAW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Contract.pdf", "content_type": "application/pdf", "size": 48213}'{
"id": "0b9d…",
"expires_at": "2026-11-14T13:30:00.000000Z",
"upload": {
"url": "https://macaaw.com/public/v1/library/uploads/0b9d…",
"method": "PUT",
"headers": {
"content-type": "application/pdf",
"content-length": "48213"
}
}
}curl -X PUT https://macaaw.com/public/v1/library/uploads/$UPLOAD_ID \
-H "Authorization: API-Key $MACAAW_API_KEY" \
-H "Content-Type: application/pdf" \
--data-binary @Contract.pdfOptionally send sha256 (hex) to have the server compare it with what it stored. The answer is the document with its versions.
Read documents and versions#
| Endpoint | What it answers |
|---|---|
GET /library/documents | Pages of documents (?page=&count=, folder_id, q). |
GET /library/documents/{id} | The document, its current version id and every version kept, with SHA-256 and the change that made it. |
GET /library/documents/{id}/versions | The versions only, newest first. |
GET /library/documents/{id}/download | The current version, or ?version=. Vault folder rules apply (403 when downloads are off). |
Render a page as PNG#
Pages start at 1. dpi is one of 36, 72, 96, 150, 200 (default 96); version defaults to the current one. Pages are drawn by the worker in its sandbox. If the picture is ready within a few seconds you get 200 image/png; otherwise 202 with retry_after — ask again.
Preview and commit an edit#
An operation is one server tool from GET /tools that takes one file of the document's type and returns the same type (for example compress-pdf, ocr-pdf or rotate-pdf). Tools run as tasks with your plan's limits and counting.
{
"base_version_id": "4",
"operations": [
{
"type": "tool",
"tool": "compress-pdf",
"options": {
"level": "recommended"
},
"page_indexes": []
}
]
}Always 202 Accepted with the task: follow it with GET /tasks/{id} or the live stream, and download its result. The document does not change.
Send preview_id to keep a finished preview — the result is saved at once and you get 201 with the edit result. Or send operations to run and save in one go — you get 202 with the operation and its task, and the new version is saved when the task finishes (GET /library/operations/{id}).
{
"status": "completed",
"documentId": "b1c2…",
"previousVersionId": "4",
"newVersionId": "5",
"operationsApplied": 1,
"warnings": [],
"validation": {
"ok": true,
"checks": {
"pdf_header": true,
"pdf_eof": true,
"pdf_parsed": true
},
"findings": []
},
"operation_id": "7e1a…"
}conflict and no version is made. Sandbox keys can preview but not commit (their results are stamped).Coming#
These parts of the platform API wait for features that are not in this release. They are listed so you can plan; no endpoint answers for them yet.
- Images (Image Studio):
POST /images/uploads,GET /images/{id},GET /images/{id}/versions,POST /images/{id}/operations/preview,POST /images/{id}/operations,POST /images/{id}/export - PDF image objects:
GET /library/documents/{id}/image-objects,POST /library/documents/{id}/images/replace