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
Designs	`POST /designs`, `GET /designs`, `GET /designs/:id`, `GET /designs/:id/tree`, `PATCH /designs/:id`, `PATCH /designs/:id/tree`, `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`

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.