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.

These are not the /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.

POST/library/uploads
Shell
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}'
201 Created
{
  "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"
    }
  }
}
PUT/library/uploads/{id}
Shell
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.pdf
POST/library/uploads/{id}/complete

Optionally 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#

EndpointWhat it answers
GET /library/documentsPages 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}/versionsThe versions only, newest first.
GET /library/documents/{id}/downloadThe current version, or ?version=. Vault folder rules apply (403 when downloads are off).

Render a page as PNG#

GET/library/documents/{id}/pages/{page}/render

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.

POST/library/documents/{id}/operations/preview
Request
{
  "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.

POST/library/documents/{id}/operations

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}).

201 Created
{
  "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…"
}
The base version is checked when you ask and again when the task finishes. If the document moved on in between, the operation ends as 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
Library documents · Macaaw API