Upload an image

POST/api/v1/library-images

POST /library-images

curl -X POST 'https://www.unitpost.com/api/v1/library-images' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'User-Agent: my-app/1.0' \
  -H 'Content-Type: application/json' \
  -d '{ }'

Response · 201

{
  "object": "library_image",
  "id": "id_123",
  "path": "string",
  "url": "https://example.com",
  "filename": "string",
  "content_type": "string",
  "size": 1,
  "width": 0,
  "height": 0,
  "alt": "string",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Add an image to the library from a public https url (fetched once, no redirects, no private addresses) or base64 data with its content_type: PNG, JPEG, GIF or WebP up to 5 MB and 16,384 px a side (50 megapixels at most), counted against the plan's image storage (403 limit_reached). Send an Idempotency-Key so a retried upload stores one image. Requires the templates:write capability.

Parameters1 field

Field	Type	Description
`Idempotency-Key`	string · header	Any unique string (1–256 characters, e.g. a UUID). Retrying with the same key and the same body within 24 hours returns the first result instead of sending again; the same key with a different body is `409 invalid_idempotent_request`, and one still in flight is `409 concurrent_idempotent_requests`.

Request body5 fields

Field	Type	Description
`url`	string	A public https image to fetch (no redirects, no private addresses). PNG, JPEG, GIF or WebP, up to 5 MB and 16,384 px a side (50 megapixels at most); anything else is a 422 naming `url`.
`data`	string	The image bytes, base64 (no `data:` prefix). Base64 adds a third, and a request over ~6 MB is refused before it arrives, so this fits about 4 MB of image; send larger images (up to 5 MB) by `url`. At most 16,384 px a side and 50 megapixels; anything else is a 422 naming `data`.
`content_type`	enumimage/png \| image/jpeg \| image/gif \| image/webp	Required with `data`; refused with `url` (the server sends the type).
`filename`	string	Shown in the library. Defaults to the URL's file name, or `image`.
`alt`	string \| null	Alt text suggested when the image is inserted.

Response · 201 fields12 fields

Field	Type	Description
`object`required	string	—
`id`required	string	—
`path`required	string	Put this in a template or design: `<Image src="/img/…">` or `<img src="/img/…">`. Template and design sends resolve it to the image host; a raw `html` send doesn't, so use `url` there.
`url`required	string	The image's public address on our asset CDN: use it in raw `html` sends and anywhere outside Unitpost.
`filename`required	string	—
`content_type`required	string	—
`size`required	integer	Bytes.
`width`required	integer \| null	—
`height`required	integer \| null	—
`alt`required	string \| null	The alt text suggested when the image is inserted.
`created_at`required	string	—
`updated_at`required	string	—

201400401403409422429502503

Upload an image

Upload an image

Search docs and guides