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/documentsSubmit 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
| Name | Where | Type | Required | Description |
|---|---|---|---|---|
| files | form | File[] | Yes | One to fifty PDF or image files (application/pdf, image/jpeg, image/png, image/webp). Each file must be ≤ 10 MB. |
| workspace | form | string | No | Logical workspace tag (e.g. "finance", "legal"). Defaults to "default". Scopes the batch in the dashboard view. |
| Authorization | header | string | Yes | Bearer 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/:idPoll 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
| Name | Where | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (cuid) | Yes | Document id returned from the Submit endpoint. |
| Authorization | header | string | Yes | Bearer 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/downloadStream 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
| Name | Where | Type | Required | Description |
|---|---|---|---|---|
| id | path | string (cuid) | Yes | Document id returned from Submit. |
| Authorization | header | string | Yes | Bearer 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.