iWork to PDF API

Planned

Convert Apple iWork files (Pages, Numbers, Keynote) to PDF.

Not yet available

iWork formats (pages, numbers, key) are not in the backend's allowed upload extensions. The conversion engine cannot parse them yet.

API Lifecycle & Flow

OrbConvert follows an asynchronous pipeline for reliability and high-throughput processing:

STEP 1

Upload

Send multipart file to POST /api/uploads. Receive fileId.

STEP 2

Queue Job

Submit JSON to POST /api/conversions. Receive conversionId.

STEP 3

Poll Status

Poll GET /api/conversions/:id until status is completed.

STEP 4

Download

Retrieve converted file via the signed outputUrl or GET /api/files/:id/download.

Authentication

All API requests require authentication. Pass your key or token in the HTTP header:

API Key

Include Authorization: Bearer <API_KEY> or x-api-key: <API_KEY>.

Authorization: Bearer ch_live_your_api_key_here

Guest Fingerprint (Testing)

For unauthenticated requests, send an x-guest-fingerprint header. Subject to guest quota.

x-guest-fingerprint: custom_client_device_id

Endpoints

POST/api/uploads

Upload the iWork file.

POST/api/conversions

Convert to PDF (toFormat: 'pdf').

GET/api/conversions/:id

Poll for completion.

Request Specification

Execute a POST request to /api/conversions:

http

POST /api/conversions HTTP/1.1
Host: api.orbconvert.com
Authorization: Bearer ch_live_your_api_key_here
Content-Type: application/json

{
  "fileId": "inputs/user/usr_abc123/uploaded_source.bin",
  "toFormat": "pdf"
}

Parameter	Type	Required	Description
fileId	string	Yes	The storage key returned by `POST /api/uploads`.
toFormat	string	Yes	Target format extension (e.g. "pdf").
jobIntent	string	No	Use `"transform"` for same-format optimization. Defaults to `"convert"`.
fileName	string	No	Original file name for format identification and download naming.
fileSize	number	No	File size in bytes for pre-conversion quota and storage checks.
options	object	No	Encoder and processing options validated for the target category.

Available Options

Options are strictly validated by the backend validator. Malformed or unrecognized options trigger a 400 Bad Request error.

Option	Type	Accepted Values	Description
metadata	string	"remove" \| "keep"	Strips or preserves document metadata (Title, Author, Creator, Subject).

Supported Formats

pages/numbers/keypdf

Response Specification

Check the status of your conversion by polling GET /api/conversions/:id. Once status reaches completed, the payload includes the download URL:

json

{
  "conversion": {
    "id": "conv_a8b2c4d6",
    "status": "completed",
    "progress": 100,
    "fromFormat": "file",
    "toFormat": "pdf",
    "outputFileId": "outputs/user/usr_abc123/conv_a8b2c4d6.pdf",
    "outputUrl": "https://api.orbconvert.com/api/files/conv_a8b2c4d6/download?token=eyJhbGciOiJIUzI1NiIs...",
    "outputSize": 284160,
    "createdAt": "2026-09-17T04:00:00.000Z",
    "completedAt": "2026-09-17T04:00:04.250Z"
  }
}

Error Handling & Status Codes

OrbConvert returns consistent JSON error envelopes for all 4xx and 5xx responses:

json

{
  "error": {
    "message": "File exceeds the 100 MB limit for free users.",
    "code": "FILE_TOO_LARGE"
  }
}

HTTP	Error Code	Cause & Resolution
400	BAD_REQUEST	Missing required fields (`fileId` or `toFormat`).
400	SAME_FORMAT_NOOP	Source and target format are identical without `"jobIntent": "transform"`.
400	UNSUPPORTED_FORMAT	Input or target format is not supported by the conversion engine.
400	INVALID_OPTIONS	An option value was outside allowed bounds or not recognized.
401	UNAUTHORIZED	Missing, invalid, or expired API Key / JWT token.
403	FORBIDDEN	Account suspended or tool temporarily disabled by administrator.
404	NOT_FOUND	The specified `fileId` or `conversionId` does not exist.
413	FILE_TOO_LARGE	File size exceeds user plan limits (Guest: 25 MB, Free: 100 MB, Pro: 2 GB).
429	QUOTA_EXCEEDED	Daily conversion count or data bandwidth quota exhausted.
429	QUEUE_FULL_USER	Pending queue concurrency cap reached (Guest: 5, Free: 10, Pro: 20).
503	QUEUE_FULL_GLOBAL	System processing queue at peak capacity. Back off and retry.
503	MAINTENANCE_MODE	Platform is undergoing scheduled maintenance.
500	CONVERSION_ERROR	Internal processing engine failed while executing conversion.

Code Examples

# 1. Upload source file
curl -X POST "https://api.orbconvert.com/api/uploads" \
  -H "Authorization: Bearer ch_live_your_api_key_here" \
  -F "file=@/path/to/input.file"

# Response: { "file": { "fileId": "inputs/user/usr_abc123/input.file", "size": 142080 } }

# 2. Start conversion job
curl -X POST "https://api.orbconvert.com/api/conversions" \
  -H "Authorization: Bearer ch_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"fileId":"inputs/user/usr_abc123/uploaded_source.bin","toFormat":"pdf"}'

# Response: { "conversionId": "conv_a8b2c4d6", "queued": false, "queueDepth": 0 }

# 3. Poll conversion status
curl "https://api.orbconvert.com/api/conversions/conv_a8b2c4d6" \
  -H "Authorization: Bearer ch_live_your_api_key_here"

# Response: { "conversion": { "status": "completed", "progress": 100, "outputUrl": "..." } }

# 4. Download converted output
curl -O -J "https://api.orbconvert.com/api/files/conv_a8b2c4d6/download?token=..."

Limits & Performance

Parameter	Guest Tier	Free Tier	Pro Tier
Max File Size	25 MB	100 MB	2 GB
Concurrent Queue	5 jobs	10 jobs	20 jobs
Daily Conversions	10 / day	25 / day	500 / day
Rate Limit	30/min · 500/hr	30/min · 500/hr	120/min · 2,000/hr
Polling Cadence	Recommended 2 – 5 seconds interval

Was this page helpful?

API Lifecycle & Flow

OrbConvert follows an asynchronous pipeline for reliability and high-throughput processing:

STEP 1

Upload

Send multipart file to POST /api/uploads. Receive fileId.

STEP 2

Queue Job

Submit JSON to POST /api/conversions. Receive conversionId.

STEP 3

Poll Status

Poll GET /api/conversions/:id until status is completed.

STEP 4

Download

Retrieve converted file via the signed outputUrl or GET /api/files/:id/download.

Authentication

All API requests require authentication. Pass your key or token in the HTTP header:

API Key

Include Authorization: Bearer <API_KEY> or x-api-key: <API_KEY>.

Authorization: Bearer ch_live_your_api_key_here

Guest Fingerprint (Testing)

For unauthenticated requests, send an x-guest-fingerprint header. Subject to guest quota.

x-guest-fingerprint: custom_client_device_id

Request Specification

Execute a POST request to /api/conversions:

http

POST /api/conversions HTTP/1.1
Host: api.orbconvert.com
Authorization: Bearer ch_live_your_api_key_here
Content-Type: application/json

{
  "fileId": "inputs/user/usr_abc123/uploaded_source.bin",
  "toFormat": "pdf"
}

Parameter	Type	Required	Description
fileId	string	Yes	The storage key returned by `POST /api/uploads`.
toFormat	string	Yes	Target format extension (e.g. "pdf").
jobIntent	string	No	Use `"transform"` for same-format optimization. Defaults to `"convert"`.
fileName	string	No	Original file name for format identification and download naming.
fileSize	number	No	File size in bytes for pre-conversion quota and storage checks.
options	object	No	Encoder and processing options validated for the target category.

Option

Type

Accepted Values

Description

metadata

string

"remove" | "keep"

Strips or preserves document metadata (Title, Author, Creator, Subject).

Response Specification

Check the status of your conversion by polling GET /api/conversions/:id. Once status reaches completed, the payload includes the download URL:

json

{
  "conversion": {
    "id": "conv_a8b2c4d6",
    "status": "completed",
    "progress": 100,
    "fromFormat": "file",
    "toFormat": "pdf",
    "outputFileId": "outputs/user/usr_abc123/conv_a8b2c4d6.pdf",
    "outputUrl": "https://api.orbconvert.com/api/files/conv_a8b2c4d6/download?token=eyJhbGciOiJIUzI1NiIs...",
    "outputSize": 284160,
    "createdAt": "2026-09-17T04:00:00.000Z",
    "completedAt": "2026-09-17T04:00:04.250Z"
  }
}

Error Handling & Status Codes

OrbConvert returns consistent JSON error envelopes for all 4xx and 5xx responses:

json

{
  "error": {
    "message": "File exceeds the 100 MB limit for free users.",
    "code": "FILE_TOO_LARGE"
  }
}

HTTP	Error Code	Cause & Resolution
400	BAD_REQUEST	Missing required fields (`fileId` or `toFormat`).
400	SAME_FORMAT_NOOP	Source and target format are identical without `"jobIntent": "transform"`.
400	UNSUPPORTED_FORMAT	Input or target format is not supported by the conversion engine.
400	INVALID_OPTIONS	An option value was outside allowed bounds or not recognized.
401	UNAUTHORIZED	Missing, invalid, or expired API Key / JWT token.
403	FORBIDDEN	Account suspended or tool temporarily disabled by administrator.
404	NOT_FOUND	The specified `fileId` or `conversionId` does not exist.
413	FILE_TOO_LARGE	File size exceeds user plan limits (Guest: 25 MB, Free: 100 MB, Pro: 2 GB).
429	QUOTA_EXCEEDED	Daily conversion count or data bandwidth quota exhausted.
429	QUEUE_FULL_USER	Pending queue concurrency cap reached (Guest: 5, Free: 10, Pro: 20).
503	QUEUE_FULL_GLOBAL	System processing queue at peak capacity. Back off and retry.
503	MAINTENANCE_MODE	Platform is undergoing scheduled maintenance.
500	CONVERSION_ERROR	Internal processing engine failed while executing conversion.

Code Examples

# 1. Upload source file
curl -X POST "https://api.orbconvert.com/api/uploads" \
  -H "Authorization: Bearer ch_live_your_api_key_here" \
  -F "file=@/path/to/input.file"

# Response: { "file": { "fileId": "inputs/user/usr_abc123/input.file", "size": 142080 } }

# 2. Start conversion job
curl -X POST "https://api.orbconvert.com/api/conversions" \
  -H "Authorization: Bearer ch_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{"fileId":"inputs/user/usr_abc123/uploaded_source.bin","toFormat":"pdf"}'

# Response: { "conversionId": "conv_a8b2c4d6", "queued": false, "queueDepth": 0 }

# 3. Poll conversion status
curl "https://api.orbconvert.com/api/conversions/conv_a8b2c4d6" \
  -H "Authorization: Bearer ch_live_your_api_key_here"

# Response: { "conversion": { "status": "completed", "progress": 100, "outputUrl": "..." } }

# 4. Download converted output
curl -O -J "https://api.orbconvert.com/api/files/conv_a8b2c4d6/download?token=..."

Parameter

Guest Tier

Free Tier

Pro Tier

Max File Size

25 MB

100 MB

2 GB

Concurrent Queue

5 jobs

10 jobs

20 jobs

Daily Conversions

10 / day

25 / day

500 / day

Rate Limit

30/min · 500/hr

120/min · 2,000/hr

Polling Cadence

Recommended 2 – 5 seconds interval

iWork to PDF API

Not yet available

API Lifecycle & Flow

Authentication

Endpoints

Request Specification

Available Options

Supported Formats

Response Specification

Error Handling & Status Codes

Code Examples

Limits & Performance

Related Resources

iWork to PDF API

Not yet available

API Lifecycle & Flow

Authentication

Endpoints

Request Specification

Available Options

Supported Formats

Response Specification

Error Handling & Status Codes

Code Examples

Limits & Performance

Related Resources