Document Hosting

pdfRelay can host your generated PDFs and provide shareable download URLs. Configure password protection, expiration dates, and download limits. Every hosted document gets an unguessable private link.

Hosting Options

To host a converted PDF, include a hosting object in your conversion request:

{
  "source": "html",
  "content": "<h1>Monthly Report - January 2025</h1>...",
  "hosting": {
    "enabled": true,
    "password": "s3cret",
    "expires_in": 2592000,
    "download_limit": 50
  }
}

Parameter	Type	Required	Description
`password`	string	No	Password required to download the document. Omit for public access.
`expires_in`	integer (seconds)	No	Time-to-live in seconds. Document becomes inaccessible after this duration (e.g. 2592000 = 30 days).
`download_limit`	integer	No	Maximum number of times the document can be downloaded. Unlimited if omitted.
`filename`	string	No	Custom filename for the downloaded file. Defaults to document.pdf.

Public Download URLs

When hosting is enabled, the conversion response includes a public download URL:

{
  "id": "conv_r8Kx2mNpQw",
  "status": "completed",
  "document_id": "doc_abc123",
  "page_count": 5,
  "duration_ms": 142,
  "download_url": "https://pdfrelay.com/d/d_kP3xNqWm7b"
}

Share the download_url with anyone who needs access to the document. If password-protected, they will be prompted to enter the password before downloading.

Managing Hosted Documents

List Documents

GET https://api.pdfrelay.com/v1/documents

Get Document Details

GET https://api.pdfrelay.com/v1/documents/:document_id

Update Document Settings

Update hosting settings for an existing document:

curl -X PATCH https://api.pdfrelay.com/v1/documents/doc_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "password": "new-password",
    "expires_at": "2025-06-01T00:00:00Z",
    "max_downloads": 100
  }'

Delete a Document

Permanently delete a hosted document and revoke its download URL:

curl -X DELETE https://api.pdfrelay.com/v1/documents/doc_abc123 \
  -H "Authorization: Bearer sk_live_..."