API Overview

The ImaginePDF REST API lets your product create designs, manage assets, and generate PDFs without a human in the loop. It is the same backend the visual editor and the Claude Code plugin use.

Base URL


https://api.imaginepdf.com

Every endpoint is mounted under /api/v1. For example, generation is POST https://api.imaginepdf.com/api/v1/designs/:id/generate.

Authentication

All requests authenticate with a workspace API key in the X-API-Key header:


X-API-Key: pc_live_xxxxxxxxxxxxxxxxxxxx

Keys are workspace-scoped and created from the dashboard. See Authentication.

The response envelope

Every response — success or error — uses the same envelope:


{
  "status": "success",
  "data": { /* the result */ },
  "error": null
}

On failure:


{
  "status": "error",
  "data": null,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description."
  }
}

status is "success" or "error".
On success, data holds the result and error is null.
On error, data is null and error has a machine-readable code and a message. See Errors for the full code table.

Always branch on the HTTP status code and error.code, not on the message text — messages may change, codes are stable.

Content types

JSON endpoints expect Content-Type: application/json.
The image upload endpoint expects multipart/form-data (a file part, ≤ 1 MB).

Endpoint map

Area	Endpoints
Authentication	`GET /me`
Designs	`POST /designs`, `GET /designs`, `GET /designs/:id`, `GET /designs/:id/tree`, `PATCH /designs/:id`, `PATCH /designs/:id/tree`
Catalogs	`GET /actions`, `GET /fonts`
Uploads	`POST /uploads`
Generate	`POST /designs/:id/generate`
Preview	`GET /designs/:id/preview?page=:n`
Batch	`POST /designs/:id/batch`, `GET /batches/:jobId`, `GET /batches/:jobId/download`

Authoring is split across two PATCH routes and it matters which you call: PATCH /designs/:id is metadata (rename, re-describe) and PATCH /designs/:id/tree is authoring (the actions batch). Sending actions to the metadata route is a 400.

Conventions used in this reference

All paths are relative to https://api.imaginepdf.com/api/v1.
Examples use a $IMAGINEPDF_API_KEY shell variable for the key.
Response bodies show the value of data unless an error is being illustrated.

Not writing HTTP by hand?

The same operations are available two other ways, both backed by this API:

The hosted MCP server at https://api.imaginepdf.com/mcp — connect Claude, Cursor or any MCP client and let the assistant call these operations as tools.
The Claude Code plugin — opinionated design and generate skills for the terminal.