API Reference

Three endpoints. Every document.Submit once. Poll until routed. Download when you need the file.

The Pilcrow document API exposes a deliberately small surface for ingesting files, polling classification status, and pulling the original bytes back. Every request is authenticated with your API key; every response is a typed JSON envelope.

01Submit
POST
/api/documents
Submit one up to fifty PDF or image files in a single multipart request. Pilcrow extracts structure, classifies each document (Invoice / Contract / Form), persists the row, and returns the typed DocumentList envelope for the submitted batch.

Parameters

NameWhereTypeRequiredDescription
filesformFile[]YesOne to fifty PDF or image files (application/pdf, image/jpeg, image/png, image/webp). Each file must be ≤ 10 MB.
workspaceformstringNoLogical workspace tag (e.g. "finance", "legal"). Defaults to "default". Scopes the batch in the dashboard view.
AuthorizationheaderstringYesBearer token: "Authorization: Bearer <PILCROW_API_KEY>".

Sample request

curl -X POST https://app.pilcrow.ai/api/documents \
  -H "Authorization: Bearer <PILCROW_API_KEY>" \
  -F "files=@./acme-invoice-2026-08.pdf" \
  -F "files=@./vendor-msa-renewal.pdf" \
  -F "workspace=finance"

Sample response

{
  "items": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9i0j1k",
      "workspace": "finance",
      "fileName": "acme-invoice-2026-08.pdf",
      "mimeType": "application/pdf",
      "size": 184320,
      "r2Key": "https://polsia.com/api/proxy/r2/files/acme-invoice-2026-08.pdf",
      "docType": "Invoice",
      "status": "Pending",
      "vendor": "Acme Industries, LLC",
      "amountCents": 1284500,
      "currency": "USD",
      "issueDate": "2026-08-12T00:00:00.000Z",
      "parties": ["Acme Industries, LLC", "Pilcrow Test Holdings"],
      "lineItems": [
        { "description": "Q3 platform license — 25 seats", "amountCents": 980000 },
        { "description": "Onboarding services", "amountCents": 304500 }
      ],
      "confidence": 0.96,
      "warnings": [],
      "createdAt": "2026-08-14T15:42:18.114Z"
    },
    {
      "id": "clx2b3c4d5e6f7g8h9i0j1k2l",
      "workspace": "finance",
      "fileName": "vendor-msa-renewal.pdf",
      "mimeType": "application/pdf",
      "size": 91240,
      "r2Key": "https://polsia.com/api/proxy/r2/files/vendor-msa-renewal.pdf",
      "docType": "Contract",
      "status": "Pending",
      "vendor": null,
      "amountCents": null,
      "currency": null,
      "issueDate": null,
      "parties": ["Northwind Logistics"],
      "lineItems": null,
      "confidence": 0.89,
      "warnings": [],
      "createdAt": "2026-08-14T15:42:21.902Z"
    }
  ],
  "rejected": []
}
02Status
GET
/api/documents/:id
Poll a single document for its current classification, user-driven status (Pending / Approved / Needs review), extracted fields, confidence score, and any non-fatal advisories from the classification pass.

Parameters

NameWhereTypeRequiredDescription
idpathstring (cuid)YesDocument id returned from the Submit endpoint.
AuthorizationheaderstringYesBearer token: "Authorization: Bearer <PILCROW_API_KEY>".

Sample request

curl https://app.pilcrow.ai/api/documents/clx1a2b3c4d5e6f7g8h9i0j1k \
  -H "Authorization: Bearer <PILCROW_API_KEY>"

Sample response

{
  "items": [
    {
      "id": "clx1a2b3c4d5e6f7g8h9i0j1k",
      "workspace": "finance",
      "fileName": "acme-invoice-2026-08.pdf",
      "mimeType": "application/pdf",
      "size": 184320,
      "r2Key": "https://polsia.com/api/proxy/r2/files/acme-invoice-2026-08.pdf",
      "docType": "Invoice",
      "status": "Pending",
      "vendor": "Acme Industries, LLC",
      "amountCents": 1284500,
      "currency": "USD",
      "issueDate": "2026-08-12T00:00:00.000Z",
      "parties": ["Acme Industries, LLC", "Pilcrow Test Holdings"],
      "lineItems": [
        { "description": "Q3 platform license — 25 seats", "amountCents": 980000 },
        { "description": "Onboarding services", "amountCents": 304500 }
      ],
      "title": null,
      "counterparty": null,
      "renewalDate": null,
      "expirationDate": null,
      "confidence": 0.96,
      "outOfScopeCategory": null,
      "outOfScopeReason": null,
      "warnings": [],
      "createdAt": "2026-08-14T15:42:18.114Z"
    }
  ],
  "rejected": []
}
03Download
GET
/api/documents/:id/download
Stream the original file bytes for a previously submitted document. The response returns the file with its persisted Content-Type, so a curl -OJ saves it under the original filename with the original MIME type preserved.

Parameters

NameWhereTypeRequiredDescription
idpathstring (cuid)YesDocument id returned from Submit.
AuthorizationheaderstringYesBearer token: "Authorization: Bearer <PILCROW_API_KEY>".

Sample request

curl -OJ https://app.pilcrow.ai/api/documents/clx1a2b3c4d5e6f7g8h9i0j1k/download \
  -H "Authorization: Bearer <PILCROW_API_KEY>"

Sample response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Length: 184320
Content-Disposition: attachment; filename="acme-invoice-2026-08.pdf"
Cache-Control: private, no-store

%PDF-1.7
%[binary file body — original bytes as submitted]

Build on it

Wire Pilcrow into the queue that already exists.

Pilcrow's surface is small on purpose. Send the file, read the status, pull the bytes when you need them — and let the always-on agent handle the routing that sits between.