Projects

Copy page

Project PDF Export

Export some or all of a project's sheets as a single PDF. The same printing pipeline used by the Calcs.com web app — Puppeteer renders each sheet, the pages are combined, and the result is uploaded to S3.

This is an asynchronous flow:

1. Kick off the export and receive an exportId.
2. Poll for status until state === "completed".
3. Download the PDF from exportUrl.

Endpoints

Code
 
POST /v1/projects/{projectId}/export   → kick off, returns exportId
GET  /v1/exports/{exportId}            → poll status, returns exportUrl

POST API Reference → · GET API Reference →

Request body

All fields are optional. If sheetIds is omitted, every sheet in the project is exported.

Field	Type	Default	Description
sheetIds	string[]	all sheets	Subset of sheet UUIDs to include.
printMode	string	"summary"	"supersummary" (one line per sheet), "summary" (standard), "details" (full working).
paperSize	string	"Letter"	"Letter" or "A4".
locale	string	"en-US"	BCP-47 locale for number and unit formatting (e.g. "en-AU", "en-GB").
includeToc	boolean	false	Include a table-of-contents page.

Response shape

Both endpoints return the same envelope:

Code
 
{
  "exportId": "8b569763-56f7-41bb-a5fe-8c44e7cf5459",
  "state": "processing",
  "progressPercent": 0,
  "exportUrl": "https://...presigned-s3-url..."
}

• state is "processing", "completed", or "failed".
• exportUrl is only valid for download once state === "completed". It is a presigned S3 URL that expires 10 minutes after each poll — every GET /v1/exports/{exportId} returns a fresh URL.

Polling pattern

A typical client polls every 1–2 seconds until completion. Small projects usually finish in a few seconds; large projects with many sheets may take 30+ seconds.

Code
 
# 1. Kick off the export
curl -X POST "https://api.calcs.com/v1/projects/{projectId}/export" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"printMode": "summary", "paperSize": "Letter"}'
# → {"exportId": "...", "state": "processing", "progressPercent": 0, "exportUrl": "..."}

# 2. Poll until completed
curl "https://api.calcs.com/v1/exports/{exportId}" \
  -H "Authorization: Bearer YOUR_API_KEY"
# → {"exportId": "...", "state": "completed", "progressPercent": 100, "exportUrl": "..."}

# 3. Download (URL expires 10 minutes after the last poll)
curl -L -o report.pdf "<exportUrl>"

Notes

• The export inherits the project's organisation watermarking — academic, trial, and unpaid organisations get a watermark stamped onto every page automatically.
• The visual formatting of each sheet matches what you would get from the Print action in the Calcs.com web app, including any project-level print preferences such as member schedules.
• If state becomes "failed", the export will not complete; kick off a new one. Common causes: an unsolved sheet, or a transient print-Lambda failure.
• The exportUrl is regenerated on every poll, so client code does not need to cache the URL from the kickoff response — just use whatever the latest poll returned.