Assets API

Assets are workspace images referenced by a stable assets:<id> ref; see Assets for the concept. All paths are relative to https://api.imaginepdf.com/api/v1.

Accepted image types: PNG, JPEG, WebP, SVG. Max size: 10 MB.

Upload an asset


POST /assets

Multipart upload of an image.

Form fields

Field	Type	Required	Notes
`file`	file	yes	The image bytes.
`name`	string	no	Display name; defaults from the filename.


curl -X POST https://api.imaginepdf.com/api/v1/assets \
  -H "X-API-Key: $IMAGINEPDF_API_KEY" \
  -F "file=@logo.png" \
  -F "name=Company Logo"

Response 201 Created


{
  "status": "success",
  "data": {
    "id": "asset_xyz789",
    "ref": "assets:asset_xyz789",
    "name": "Company Logo",
    "mimeType": "image/png",
    "fileSize": 54321,
    "dimensions": { "width": 200, "height": 100 },
    "thumbnailUrl": "https://storage.imaginepdf.com/...",
    "isPlaceholder": false,
    "createdAt": "2026-06-08T12:00:00Z"
  },
  "error": null
}

Use the returned ref (assets:asset_xyz789) inside image elements in a design.

Create a placeholder


POST /assets/placeholder

Creates a labeled gray-box asset to stand in until a real image exists.

Body

Field	Type	Required	Notes
`name`	string	yes	Display name.
`label`	string	no	Text shown on the box, max 40 chars; defaults to `name`.
`width`	number	no	16–2000, default 400.
`height`	number	no	16–2000, default 300.


curl -X POST https://api.imaginepdf.com/api/v1/assets/placeholder \
  -H "X-API-Key: $IMAGINEPDF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Company Logo", "label": "LOGO", "width": 200, "height": 100 }'

Response 201 Created — same shape as an uploaded asset, with "isPlaceholder": true.

Replace asset content


PUT /assets/:assetId/content

Replaces the asset’s bytes in place. The ref stays the same, so designs referencing it need no change.


curl -X PUT https://api.imaginepdf.com/api/v1/assets/asset_xyz789/content \
  -H "X-API-Key: $IMAGINEPDF_API_KEY" \
  -F "file=@new-logo.png"

Response 200 OK — the updated asset object.

This is how the placeholder workflow resolves: create a placeholder, build the design against its ref, then PUT the real image when it is ready.

List assets


GET /assets

Paginated list of the workspace’s image assets.

Query parameters

Param	Type	Notes
`cursor`	string	Pagination cursor.
`limit`	number	Page size, 1–200.


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

Response 200 OK


{
  "status": "success",
  "data": {
    "items": [ { "id": "asset_xyz789", "ref": "assets:asset_xyz789", "name": "Company Logo", "...": "..." } ],
    "nextCursor": null
  },
  "error": null
}

Get an asset


GET /assets/:assetId

Returns a single asset by id.


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

Response 200 OK — the asset object.