> ## Documentation Index
> Fetch the complete documentation index at: https://connectionshub.atlastube.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# PDF export

> Export some or all of a project's sheets as a single PDF report.

Export some or all of a project's sheets as a single PDF. It is the same report you get from **Print** in the app.

This is an **asynchronous** flow:

1. Start the export and receive an `exportId`.
2. Poll until `state` is `completed`.
3. Download the PDF from `exportUrl`.

## Endpoints

```
POST /v1/projects/{projectId}/export   → start, returns exportId
GET  /v1/exports/{exportId}            → poll status, returns exportUrl
```

[Export Project to PDF](https://connectionshub.atlastube.com/docs/api/reference/projects/export-project-to-pdf.md) · [Get Export Status](https://connectionshub.atlastube.com/docs/api/reference/projects/get-export-status.md)

## Request body

All fields are optional. Without `sheetIds`, every sheet in the project is exported.

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

### Selecting sheets

Every ID in `sheetIds` must belong to the project. If any well-formed ID does not, the request is rejected with **`422 Unprocessable Entity`**, each offending ID is named, and no export starts:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "One or more sheetIds do not belong to this project.",
    "details": [
      { "field": "sheetIds", "message": "Sheet 00000000-0000-4000-8000-000000000000 does not belong to this project." }
    ]
  }
}
```

A malformed request (empty `sheetIds`, a non-UUID, or an invalid `printMode` or `paperSize`) returns `400 Bad Request` with the same envelope.

## Response

Both endpoints return the same shape. `exportUrl` is `null` until `state` is `completed`:

```json theme={null}
// still rendering: poll again
{ "exportId": "8b569763-56f7-41bb-a5fe-8c44e7cf5459", "state": "processing", "progressPercent": 0, "exportUrl": null }

// ready to download
{ "exportId": "8b569763-56f7-41bb-a5fe-8c44e7cf5459", "state": "completed", "progressPercent": 100, "exportUrl": "https://...presigned-url..." }

// failed: progressPercent stays where it stopped; start a new export
{ "exportId": "8b569763-56f7-41bb-a5fe-8c44e7cf5459", "state": "failed", "progressPercent": 50, "exportUrl": null }
```

`state` is `processing`, `completed`, or `failed`. `exportUrl` is `null` while `processing` or `failed`. Once `completed`, it is a presigned URL that expires **10 minutes after each poll**. Every poll returns a fresh one.

## Polling

Poll `GET /v1/exports/{exportId}` until `state` is `completed` or `failed`, with backoff rather than a tight loop. Small projects usually finish in a few seconds; large ones can take 30 seconds or more.

```bash theme={null}
# 1. Start 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"}'

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

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

## Notes

* Formatting matches **Print** in the app, including project-level print preferences such as member schedules.
* The export carries the organisation's watermark, if it has one.
* If `state` becomes `failed`, the export will not complete; start a new one. Common causes are an unsolved sheet or a temporary rendering failure.
* Use the `exportUrl` from the latest poll; there is no need to cache it.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.