Managed PDF Lifecycle

Managed PDFs are render outputs persisted as named assets. They survive the render job that created them and are available until explicitly deleted.

Managed PDFs are created by setting outputMode: "managed" when creating a render job. The PDF remains accessible independently of the render job — the job can be deleted while the PDF persists.

List managed PDFs

Request: GET /v1/pdfs

curl -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  "$PRESS_CLOUD_API/v1/pdfs"

Optionally filter by deploy:

curl -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  "$PRESS_CLOUD_API/v1/pdfs?deployId=dpl_abc123"

Response: 200 OK

{
  "items": [
    {
      "id": "pdf_abc123",
      "state": "available",
      "fileName": "invoice-2026-04-28.pdf",
      "bytes": 204800,
      "pageCount": 4,
      "deployId": "dpl_abc123",
      "deployVersionId": "dv_456",
      "renderJobId": "rj_abc123",
      "businessKey": "invoice-2026-04-28",
      "createdAt": 1745800050000
    }
  ]
}

Paginate with the cursor query parameter (see Cursor Pagination).

Error handling: An empty items array means no PDFs match the filter — not an error.

Get a managed PDF

Request: GET /v1/pdfs/{pdfId}

curl -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  "$PRESS_CLOUD_API/v1/pdfs/pdf_abc123"

Response: 200 OK

{
  "pdf": {
    "id": "pdf_abc123",
    "state": "available",
    "fileName": "invoice-2026-04-28.pdf",
    "bytes": 204800,
    "pageCount": 4,
    "deployId": "dpl_abc123",
    "deployVersionId": "dv_456",
    "renderJobId": "rj_abc123",
    "businessKey": "invoice-2026-04-28",
    "createdAt": 1745800050000
  }
}

Error handling: 404 if the PDF ID does not exist.

Download a managed PDF

Request: POST /v1/pdfs/{pdfId}/download

curl -X POST "$PRESS_CLOUD_API/v1/pdfs/pdf_abc123/download" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN"

Specify a custom lifetime in the JSON request body:

curl -X POST "$PRESS_CLOUD_API/v1/pdfs/pdf_abc123/download" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expiresInSeconds":3600}'

Response: 200 OK

{
  "access": {
    "url": "https://storage.pressjs.dev/pdf_abc123?signature=...",
    "expiresAt": 1745800650000
  }
}

When expiresInSeconds is omitted, the signed URL expires after 10 minutes. Generate a new one when it expires.

Preview a managed PDF

Request: POST /v1/pdfs/{pdfId}/preview

curl -X POST "$PRESS_CLOUD_API/v1/pdfs/pdf_abc123/preview" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN"

Preview links also accept expiresInSeconds:

curl -X POST "$PRESS_CLOUD_API/v1/pdfs/pdf_abc123/preview" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"expiresInSeconds":3600}'

Response: 200 OK — same structure as download, but the signed URL renders the PDF inline in a browser.

Error handling: 404 if the PDF does not exist. 409 if the PDF is in deleting state. 503 if the provider is not ready.

Permanent links

Permanent links are public download URLs for a managed PDF. They stay active until the link is deleted or the PDF is deleted.

List permanent links

Request: GET /v1/pdfs/{pdfId}/permanent-links

curl -H "Authorization: Bearer $PRESS_CLOUD_TOKEN" \
  "$PRESS_CLOUD_API/v1/pdfs/pdf_abc123/permanent-links"

Response: 200 OK

{
  "items": [
    {
      "id": "ppl_abc123",
      "pdfId": "pdf_abc123",
      "url": "https://storage.pressjs.dev/permanent/pdfs/ppl_abc123.pdf",
      "createdAt": 1745800050000
    }
  ]
}

Create a permanent link

Request: POST /v1/pdfs/{pdfId}/permanent-links

curl -X POST "$PRESS_CLOUD_API/v1/pdfs/pdf_abc123/permanent-links" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN"

Response: 201 Created

{
  "link": {
    "id": "ppl_abc123",
    "pdfId": "pdf_abc123",
    "url": "https://storage.pressjs.dev/permanent/pdfs/ppl_abc123.pdf",
    "createdAt": 1745800050000
  }
}

Delete a permanent link

Request: DELETE /v1/pdfs/{pdfId}/permanent-links/{linkId}

curl -X DELETE "$PRESS_CLOUD_API/v1/pdfs/pdf_abc123/permanent-links/ppl_abc123" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN"

Response: 204 No Content

Error handling: 404 if the PDF or permanent link does not exist.

Delete a managed PDF

Request: DELETE /v1/pdfs/{pdfId}

curl -X DELETE "$PRESS_CLOUD_API/v1/pdfs/pdf_abc123" \
  -H "Authorization: Bearer $PRESS_CLOUD_TOKEN"

Once deleted, the PDF is marked as deleting and eventually purged. The deletion is not reversible. Permanent links for the PDF stop resolving after the PDF is deleted.

Response: 204 No Content

Error handling: 404 if the PDF does not exist.