Client API v1 — Dokumentation

Overview

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/.

Authentication

Getting a key

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.

Sending the key

Pass the key in one of two ways:

With Authorization (recommended):

Authorization: Bearer webviewpdf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

With X-Api-Key:

X-Api-Key: webviewpdf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Token format

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.

Limits

Rate limiting

120 requests/min per IP across all /api/v1/* endpoints. Exceeding it returns 429 Too Many Requests.

Request size

File uploads: 512 MB. All other endpoints: 10 MB. Upload limits also follow the workspace plan.

API reference

GET /api/v1/flipbooks List flipbooks

A paginated list of the workspace flipbooks, with search and filtering.

Query parameters

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`

200 response

{
  "flipbooks": [ /* Flipbook[] */ ],
  "page": 1,
  "per_page": 10,
  "total_pages": 1
}

Example

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

GET /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.

Path parameters

Parameter	Type	Description
id	UUID	Flipbook ID

200 response

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.

Example

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

POST /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.

Request body (multipart/form-data)

Field	Type	Required	Description
file	file	yes	PDF file
title	string	no	Title (defaults to the file name)

201 response

{
  "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
}

Example

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

POST /api/v1/flipbooks/:id/versions Create a version

Uploads a new PDF as an additional version of an existing flipbook.

Request body (multipart/form-data)

Field	Type	Required	Description
file	file	yes	PDF file for the new version
activate	string	no	Activate automatically once processing finishes (default: `true`)

201 response

{
  "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
}

Example

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

POST /api/v1/flipbooks/:id/versions/:vid/activate Activate a version

Makes the given version active. The previously active version is deactivated automatically.

Path parameters

Parameter	Type	Description
id	UUID	Flipbook ID
vid	UUID	Version ID

200 response

{
  "success": true,
  "active_version_id": "0199abcd-9999-7def-8888-234567890def"
}

Example

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

GET /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.

200 response

{
  "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

DELETE /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.

200 response

{"success": true}

Example

curl -X DELETE "https://webviewpdf.com/api/v1/flipbooks/UUID/versions/UUID" \
  -H "Authorization: Bearer webviewpdf_xxx..."

Errors: 400 Invalid IDs, 422 — service error

Response codes

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"}.

Data types

Flipbook

{
  "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 */ ]
}

Version

{
  "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"
}

Page

{
  "id": "uuid",
  "position": "int",
  "width": "int",
  "height": "int",
  "img_max": "image URL",
  "img_mid": "image URL",
  "img_min": "image URL"
}