Skip to Content
ConceptsAssets

Assets & uploads

Every image in a design is referenced by a stable ref in its data.src (or a page/document backgroundImage). There are two ref schemes, by origin:

  • assets:<id> — the user’s editor asset library (images they upload in the app). Curated and browsable in the editor.
  • uploads:<id> — programmatic / API images (what you upload via the API, plus images authored by the Claude plugin) and inline images the server stored for you. Deliberately kept OUT of the user’s library so automated runs don’t clutter it.

Both resolve identically when a PDF is rendered. Over the API you create uploads: images; you reference existing assets: images by ref if you already have one.

Uploading an image (API)

POST /api/v1/uploads takes multipart/form-data and returns an uploads:<id>:

curl -X POST https://api.imaginepdf.com/api/v1/uploads \
  -H "X-API-Key: $IMAGINEPDF_API_KEY" \
  -F "file=@logo.png" \
  -F "name=Company Logo"
{
  "uploadId": "upl_xyz789",
  "ref": "uploads:upl_xyz789",
  "name": "Company Logo",
  "mimeType": "image/png",
  "fileSize": 54321,
  "dimensions": { "width": 200, "height": 100 },
  "thumbnailUrl": "https://storage.imaginepdf.com/...",
  "createdAt": "2026-06-08T12:00:00Z"
}

Accepted types: PNG, JPEG, WebP, SVG. Maximum size: 1 MB. SVGs are rasterized to PNG on upload (and a blank SVG is rejected), so artwork renders identically on the canvas and in the PDF.

Drop the returned ref into an image element’s data.src. A small inline data:image/...;base64,… src works too — the server uploads it to uploads for you so the design tree never carries raw image bytes.

Need to change an image later? Upload the new one and point the element’s data.src at its new ref with an update_element action. There’s no in-place “replace bytes” and no placeholder box — author a real image up front (an SVG is ideal: crisp at any size, never a gray placeholder).

Last updated on
VariablesCredits & plans