Skip to Content
Quickstart

Quickstart

This guide takes you from nothing to a downloadable PDF using the REST API. It takes about five minutes.

The base URL for all API requests is:

https://api.imaginepdf.com

Every endpoint lives under /api/v1 and is authenticated with a workspace API key sent in the X-API-Key header.

1. Get an API key

  1. Sign in at imaginepdf.com .
  2. Go to Settings → API Keys.
  3. Create a key. It looks like pc_live_… and is shown only once — copy it somewhere safe.

API keys are scoped to a single workspace. See Authentication for details.

API access is a plan feature. If your workspace plan does not include API keys, key creation is disabled. See Credits & plans.

2. Create a design

A design is a document layout. Creating it and authoring it are two steps: first create the design to get a designId, then add content to it. Create allocates the design only — a name and an optional description — and starts with one blank A4 page. (It does not take actions; sending them returns a 400.)

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

The response carries the new designId — you’ll author against it next:

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

3. Add content with actions

Build the design by sending an ordered batch of actions to PATCH /api/v1/designs/:id. Each action does one thing; the list applies in order, atomically. The smallest useful batch is two actions: add a text element and bind it as a variable.

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 '{
    "actions": [
      {
        "type": "add_element",
        "args": {
          "type": "text",
          "name": "customer_name",
          "position": { "x": 48, "y": 48 },
          "data": { "content": "Acme Corp" },
          "styles": { "fontSize": 24, "fontWeight": 700 }
        }
      },
      { "type": "bind_variable", "args": { "name": "customer_name" } }
    ]
  }'

Three things to notice:

  • No element id — ids are server-minted; the element’s name is how you (and bind_variable) refer to it.
  • No width/height — the text box is derived from the content and font. The "Acme Corp" here is representative sample content; size your samples like real values.
  • Binding is by name — the element’s name becomes the variable name you fill at generation time.

The response carries one result per action — including the minted id and the derived box:

{
  "status": "success",
  "data": {
    "designId": "design_abc123",
    "name": "Hello Invoice",
    "results": [
      {
        "type": "add_element",
        "status": "success",
        "data": {
          "id": "text-cfd23",
          "name": "customer_name",
          "type": "text",
          "position": { "x": 48, "y": 48, "w": 142, "h": 36 }
        }
      },
      { "type": "bind_variable", "status": "success", "data": { /* … */ } }
    ]
  },
  "error": null
}

The batch is atomic — if any action fails, nothing is saved and the error names the failing index. Just fix it and re-send the PATCH against the same designId; you never re-create the design.

The exact args for every action come from the authoring action catalog, validated server-side. Fetch it any time with GET /api/v1/actions. Text and table sizes are always derived — see Designs.

4. Generate a PDF

Render the design, filling the customer_name variable — the supplied value replaces the bound element’s content. Generation costs one credit.

curl -X POST "https://api.imaginepdf.com/api/v1/designs/design_abc123/generate" \
  -H "X-API-Key: $IMAGINEPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "customer_name": "Globex Inc" } }'

The response gives you a temporary download URL:

{
  "status": "success",
  "data": {
    "designId": "design_abc123",
    "filename": "Hello Invoice.pdf",
    "downloadUrl": "https://storage.imaginepdf.com/....pdf?signature=...",
    "expiresIn": 3600,
    "status": "completed"
  },
  "error": null
}

Open downloadUrl in a browser (or curl -L -o out.pdf "<downloadUrl>"). The link is valid for one hour (expiresIn seconds).

5. Preview without spending credits

While iterating, render a single page to a PNG instead — this is free:

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

Next steps

Last updated on
IntroductionDesigns