Designs API

Designs are document layouts. You build and edit them by sending actions — each action is { type, args } and does one thing (add one element, bind one variable). Actions apply sequentially and atomically; see Designs for the concept. All paths below are relative to https://api.imaginepdf.com/api/v1.

Create a design

Creates a design — a name, an optional description, and the paper format. Create allocates the design only; it does not author content. You build it by sending actions to PATCH /designs/:id/tree. Posting actions to this endpoint is rejected with a 400 — creation and authoring are separate steps.

Body

The design’s first page is born at the requested format, so set it here rather than flipping the page afterwards. width/height are taken literally — orientation is ignored for a custom sheet — and sending both a size and custom dimensions is a 400. To change the paper on an existing design, use the update_page action.

The body is strict: any unknown key, actions included, is a loud 400 rather than a silently-ignored create.

curl -X POST https://api.imaginepdf.com/api/v1/designs \
  -H "X-API-Key: $IMAGINEPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice",
    "description": "Standard invoice template"
  }'

Response 201 Created

{
  "status": "success",
  "data": {
    "designId": "design_abc123",
    "name": "Invoice",
    "description": "Standard invoice template",
    "createdAt": "2026-06-08T12:00:00Z"
  },
  "error": null
}

Take the designId and author the design with PATCH /designs/:id/tree: it applies your actions batch and returns one result per action — each echoing the minted id and the derived box (no element id or w/h is ever sent; both come back).

List designs

Returns designs in the workspace, paginated. Folders are excluded.

Query parameters

curl "https://api.imaginepdf.com/api/v1/designs?limit=50" \
  -H "X-API-Key: $IMAGINEPDF_API_KEY"

Response 200 OK

{
  "status": "success",
  "data": {
    "items": [
      {
        "designId": "design_abc123",
        "name": "Invoice",
        "description": "Standard invoice template",
        "fileSize": 12345,
        "createdAt": "2026-06-08T12:00:00Z",
        "modifiedAt": "2026-06-08T12:00:00Z"
      }
    ],
    "nextCursor": null
  },
  "error": null
}

When nextCursor is non-null, pass it back as cursor to fetch the next page.

Get a design (metadata)

Returns the design’s metadata only — not the tree. Cheap: read names and timestamps without pulling the whole layout. Fetch the layout separately with GET /designs/:id/tree.

curl https://api.imaginepdf.com/api/v1/designs/design_abc123 \
  -H "X-API-Key: $IMAGINEPDF_API_KEY"

Response 200 OK

{
  "status": "success",
  "data": {
    "designId": "design_abc123",
    "name": "Invoice",
    "description": "Standard invoice template",
    "fileSize": 12345,
    "createdAt": "2026-06-08T12:00:00Z",
    "modifiedAt": "2026-06-08T12:00:00Z"
  },
  "error": null
}

Get the design tree

Returns the full design tree (the pdftreejs PDFTree) as raw JSON. This is the one endpoint that does not use the {status, data, error} envelope — the response body IS the tree (errors still come back enveloped). Fetch it to inspect the layout before sending a tree patch.

curl https://api.imaginepdf.com/api/v1/designs/design_abc123/tree \
  -H "X-API-Key: $IMAGINEPDF_API_KEY"

Response 200 OK (raw — no envelope)

{
  "metadata": { "schemaVersion": "v1" },
  "pages": [ /* ... */ ],
  "nodes": { /* ... */ }
}

Update a design (metadata)

Rename / re-describe. Metadata only — it never touches the tree. Provide at least one of name, description.

curl -X PATCH https://api.imaginepdf.com/api/v1/designs/design_abc123 \
  -H "X-API-Key: $IMAGINEPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Invoice (2026)", "description": "Updated template" }'

Response 200 OK — { designId, name, description, fileSize, modifiedAt }.

Update the tree

Apply an ordered batch of authoring actions — including the first batch on a freshly-created design. Body: { "actions": [ … ] } (1–500 actions).

curl -X PATCH https://api.imaginepdf.com/api/v1/designs/design_abc123/tree \
  -H "X-API-Key: $IMAGINEPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "actions": [
      {
        "type": "update_element",
        "args": {
          "name": "title",
          "data": { "content": "INVOICE #2026-001" }
        }
      },
      { "type": "bind_variable", "args": { "name": "title" } }
    ]
  }'

Existing elements are addressed by their unique name (or by the minted id — exactly one of the two). The batch is atomic: if any action fails, nothing is saved and the error names the failing index, e.g. actions[1] (bind_variable) failed: ….

Response 200 OK

{
  "status": "success",
  "data": {
    "designId": "design_abc123",
    "fileSize": 13002,
    "modifiedAt": "2026-06-08T12:05:00Z",
    "results": [ /* one result per action, in order */ ]
  },
  "error": null
}

The actions

Sizing is derived

Clients never set what the system computes. The position shape depends on the element type:

Sending w/h for a text or table is rejected with an error that names the fix (e.g. position.w is not allowed for text — width is derived; use position.maxWidth). Every add_element / update_element result echoes the final derived box.

Data by type

data is the element’s semantic payload; like position, its shape follows the type.

Get the action catalog

Returns every authoring action and its args schema. Use this to discover what actions[].args should contain.

curl https://api.imaginepdf.com/api/v1/actions \
  -H "X-API-Key: $IMAGINEPDF_API_KEY"

Response 200 OK

{
  "status": "success",
  "data": {
    "actions": [
      { "name": "add_element", "description": "...", "args": { /* schema */ } },
      { "name": "bind_variable", "description": "...", "args": { /* schema */ } }
    ]
  },
  "error": null
}

Get the font catalog

Returns every font the product supports. The catalog is deterministic and closed: the editor’s picker offers exactly these, and styles.fontFamily is validated against them — there is no runtime font registration, so a family that is not here cannot be used.

Each entry’s id is the proper family name, and that is the string you put in styles.fontFamily.

curl https://api.imaginepdf.com/api/v1/fonts \
  -H "X-API-Key: $IMAGINEPDF_API_KEY"

Response 200 OK

{
  "status": "success",
  "data": {
    "fonts": [
      { "id": "Inter", "class": "sans", "source": "google", "weights": [400, 500, 600, 700], "tags": ["recommended"] },
      { "id": "Playfair Display", "class": "serif", "source": "google", "weights": [400, 700] }
    ]
  },
  "error": null
}