REST API for managing flipbooks programmatically — create a flipbook, upload new file versions, activate a version and track processing status
The WebViewPDF Client API lets you automate publishing PDF documents. A typical flow: you upload a PDF, get back flipbook_id and version_id, then poll the processing status; once it reaches done the flipbook is ready.
The API base URL is https://webviewpdf.com/api/v1/.
API keys are created in the dashboard: Profile → API keys (/app/profile/api-keys).
Available on the Team plan only. You can set an expiry date when you create a key.
Important: the token is shown only once, right after you create it. Copy it immediately — it cannot be recovered.
Pass the key in one of two ways:
With Authorization (recommended):
Authorization: Bearer webviewpdf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
With X-Api-Key:
X-Api-Key: webviewpdf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Format: webviewpdf_ plus 48 hexadecimal characters.
Only the SHA-256 hash of the token is stored in the database — the token itself cannot be recovered from the hash.
120 requests/min per IP across all /api/v1/* endpoints. Exceeding it returns 429 Too Many Requests.
File uploads: 512 MB. All other endpoints: 10 MB. Upload limits also follow the workspace plan.
/api/v1/flipbooks
List flipbooks
A paginated list of the workspace flipbooks, with search and filtering.
| Parameter | Type | Default | Description |
|---|---|---|---|
| page | int | 1 | Page number (≥ 1) |
| per_page | int | 20 | Items per page (1–100) |
| search | string | — | Search by title |
| status | string | — | Filter: published, archived |
| sort | string | created_at | Sort field |
| dir | string | desc | Direction: asc, desc |
{
"flipbooks": [ /* Flipbook[] */ ],
"page": 1,
"per_page": 10,
"total_pages": 1
}
curl -X GET "https://webviewpdf.com/api/v1/flipbooks?page=1&per_page=10&status=published" \ -H "Authorization: Bearer webviewpdf_xxx..."
Errors: 401 Unauthorized, 400 Workspace not found, 500 Failed to list flipbooks
/api/v1/flipbooks/:id
Get a flipbook
Full details of a flipbook: every version, plus the pages of the active version — the ones a reader sees.
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Flipbook ID |
A Flipbook object with all versions[] (newest first) and a pages[] field holding the pages of the active version. The list endpoint returns no pages, and its versions holds the active version only.
curl -X GET "https://webviewpdf.com/api/v1/flipbooks/0199abcd-1234-7abc-8901-234567890abc" \ -H "Authorization: Bearer webviewpdf_xxx..."
Errors: 400 Invalid flipbook ID, 404 Flipbook not found
/api/v1/flipbooks
Create a flipbook
Uploads a PDF file and creates a new flipbook. Processing is asynchronous — the response comes back immediately with status pending.
| Field | Type | Required | Description |
|---|---|---|---|
| file | file | yes | PDF file |
| title | string | no | Title (defaults to the file name) |
{
"flipbook_id": "0199abcd-1234-7abc-8901-234567890abc",
"version_id": "0199abcd-8765-7def-4321-234567890def",
"title": "Catalog 2026",
"status": "pending",
"file_size": 5242880,
"estimated_seconds": 30.5,
"created_at_unix": 1718123456
}
curl -X POST "https://webviewpdf.com/api/v1/flipbooks" \ -H "Authorization: Bearer webviewpdf_xxx..." \ -F "file=@catalog.pdf" \ -F "title=Catalog 2026"
Errors: 400 file is required, 422 — service error
/api/v1/flipbooks/:id/versions
Create a version
Uploads a new PDF as an additional version of an existing flipbook.
| Field | Type | Required | Description |
|---|---|---|---|
| file | file | yes | PDF file for the new version |
| activate | string | no | Activate automatically once processing finishes (default: true) |
{
"version_id": "0199abcd-9999-7def-8888-234567890def",
"version_status": "pending",
"activate_on_done": true,
"file_size": 6291456,
"estimated_seconds": 35.2,
"created_at_unix": 1718124567
}
curl -X POST "https://webviewpdf.com/api/v1/flipbooks/UUID/versions" \ -H "Authorization: Bearer webviewpdf_xxx..." \ -F "file=@catalog_v2.pdf" \ -F "activate=true"
Errors: 400 Invalid flipbook ID, 400 file is required, 422 — service error
/api/v1/flipbooks/:id/versions/:vid/activate
Activate a version
Makes the given version active. The previously active version is deactivated automatically.
| Parameter | Type | Description |
|---|---|---|
| id | UUID | Flipbook ID |
| vid | UUID | Version ID |
{
"success": true,
"active_version_id": "0199abcd-9999-7def-8888-234567890def"
}
curl -X POST "https://webviewpdf.com/api/v1/flipbooks/UUID/versions/UUID/activate" \ -H "Authorization: Bearer webviewpdf_xxx..."
Errors: 400 Invalid IDs, 422 — service error
/api/v1/flipbooks/:id/versions/:vid/status
Version status
Returns the current processing status of a version. Use it to poll for readiness after an upload.
{
"version_id": "0199abcd-9999-7def-8888-234567890def",
"status": "done",
"is_active": true,
"version": 2,
"pages": 24,
"file_name": "catalog_v2.pdf",
"file_size": 6291456
}
| Field | Description |
|---|---|
| status | pending / processing / done / error |
| is_active | Whether this version is the active one |
| version | Version number |
| pages | Number of pages (0 while pending) |
| file_name | Original file name |
| file_size | Size in bytes |
Errors: 400 Invalid IDs, 404 Version not found
/api/v1/flipbooks/:id/versions/:vid
Delete a version
Deletes an inactive version of a flipbook.
The active version cannot be deleted — activate another version first.
{"success": true}
curl -X DELETE "https://webviewpdf.com/api/v1/flipbooks/UUID/versions/UUID" \ -H "Authorization: Bearer webviewpdf_xxx..."
Errors: 400 Invalid IDs, 422 — service error
| Code | Description |
|---|---|
| 200 | Request succeeded |
| 201 | Resource created (flipbook or version) |
| 400 | Invalid request parameters |
| 401 | Missing or invalid API key |
| 404 | Resource not found |
| 422 | Business logic error (quotas, restrictions, file format) |
| 429 | Rate limit exceeded (120/min) |
| 500 | Internal server error |
Every error returns a body in the form {"error": "description"}.
{
"id": "uuid",
"title": "string",
"slug": "string",
"description": "string",
"status": "published | archived",
"url": "reader link",
"created_at": "datetime",
"updated_at": "datetime",
"versions": [ /* Version[] */ ],
"pages": [ /* Page[], GET /flipbooks/:id only */ ]
}
{
"id": "uuid",
"version": "int",
"status": "pending|processing|done|error",
"is_active": "bool",
"activate_on_done": "bool",
"file_name": "string",
"file_type": "string",
"mime_type": "string",
"file_size": "int64",
"width": "int",
"height": "int",
"created_at": "datetime"
}
{
"id": "uuid",
"position": "int",
"width": "int",
"height": "int",
"img_max": "image URL",
"img_mid": "image URL",
"img_min": "image URL"
}