Designs API

Designs are document layouts. You build and edit them by passing tool calls; see Designs for the concept. All paths below are relative to https://api.imaginepdf.com/api/v1.

Create a design


POST /designs

Creates a design, optionally applying an initial list of tool calls.

Body

Field	Type	Required	Notes
`name`	string	yes	Display name.
`description`	string	no	Optional description.
`tools`	array	no	Tool calls to apply on creation.


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",
    "tools": [
      { "tool": "add_page", "input": {} }
    ]
  }'

Response 201 Created


{
  "status": "success",
  "data": {
    "designId": "design_abc123",
    "name": "Invoice",
    "description": "Standard invoice template",
    "createdAt": "2026-06-08T12:00:00Z",
    "results": [ /* one result per tool, or null if no tools */ ]
  },
  "error": null
}

List designs


GET /designs

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

Query parameters

Param	Type	Notes
`parentId`	string	Filter to a folder’s children.
`cursor`	string	Pagination cursor from a previous `nextCursor`.
`limit`	number	Page size, 1–200.


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


GET /designs/:id

Returns the full design, including its config (the design tree) and variables.


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",
    "config": { /* full design tree from pdftreejs */ },
    "variables": { "customer_name": { /* schema */ } },
    "fileSize": 12345,
    "createdAt": "2026-06-08T12:00:00Z",
    "modifiedAt": "2026-06-08T12:00:00Z"
  },
  "error": null
}

Update a design


PATCH /designs/:id

Rename, re-describe, and/or apply more tool calls. Provide at least one of name, description, tools.


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 '{
    "tools": [
      {
        "tool": "add_element",
        "input": {
          "type": "text",
          "text": "Invoice #{{invoice_number}}",
          "x": 48, "y": 48, "width": 400, "fontSize": 24
        }
      }
    ]
  }'

Response 200 OK


{
  "status": "success",
  "data": {
    "designId": "design_abc123",
    "name": "Invoice",
    "description": "Standard invoice template",
    "fileSize": 13002,
    "modifiedAt": "2026-06-08T12:05:00Z",
    "results": [ /* tool results, if tools were applied */ ]
  },
  "error": null
}

Get the tool catalog


GET /tools

Returns every authoring tool and its input schema. Use this to discover what tools[].input should contain.


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

Response 200 OK


{
  "status": "success",
  "data": {
    "tools": [
      { "name": "add_page", "description": "...", "input": { /* schema */ } },
      { "name": "add_element", "description": "...", "input": { /* schema */ } }
    ]
  },
  "error": null
}

Tool inputs are validated server-side by pdftreejs. The exact field names and constraints live in the catalog — treat GET /tools as the source of truth rather than hard-coding shapes from these examples.