AssetsImages

Images

Retrieve All Asset Images #

Method
GET
Endpoint

Retrieves all images for an Asset.

Parameters
Name Type Required? Description Details
asset_id Number Yes
The ID of the Asset whose images to use, from Retrieve Assets (GET /v1/assets) or its create response.
$include_record_revision Boolean No
Whether to include the gallery revision.
Default: false. True returns one object containing images and record_revision, including an empty gallery. Omit it for the usual JSON image array. This GET does not offer a separate response format option.

Using the image list

The gallery contains up to five images. display_rank starts at 1 in the returned order. An empty gallery returns an empty array.

Use the returned image_filename values when retrieving, downloading, deleting or reordering images.

Checking gallery changes

Request $include_record_revision=true to receive one record_revision for the entire gallery beside its images array. Send that record_revision as expected_revision when deleting or reordering images.

record_revision covers the saved image references, complete order and gallery times. It does not cover file contents or core Asset details. It belongs to the selected Asset, including when its gallery is empty.

Image filenames and access

Treat the filenames returned by GET /v1/assets/images as opaque values. Use them with the selected Asset ID. Shared Assets' images are managed in the Asset's original workspace.

Editing an image on the website gives it a new image_filename. List the images again to get the current names.

Code Samples
curl -X GET "https://api.exhibitday.com/v1/assets/images?asset_id=12345" -H "Authorization: Bearer YOUR_API_KEY"

Example response

[
  {
    "asset_id": 12345,
    "image_filename": "98765-12345-a1941c59-59cb-4b7d-b7a7-2f82f8bf84ab.jpg",
    "display_rank": 1,
    "image_last_update_timestamp": "2026-01-15T17:00:00Z"
  },
  {
    "asset_id": 12345,
    "image_filename": "98765-12345-59f0a281-df13-4bc9-acf1-3c12c25b1d25.jpg",
    "display_rank": 2,
    "image_last_update_timestamp": "2026-01-15T17:00:00Z"
  }
]

Add an Asset Image #

Method
POST
Endpoint

Adds an image to an Asset.

Parameters
Name Type Required? Description Details
asset_id Number Yes
The ID of the Asset whose images to use, from Retrieve Assets (GET /v1/assets) or its create response.
file File (multipart) Yes
One PNG, JPEG or GIF image.

Maximum size per file: 19.55 MiB (20,500,000 bytes).

Allowed file types: .png, .jpg, .jpeg, .gif.

Maximum files per request: 1.

View value format and limits

File uploads use multipart form data. Other structured values use a JSON object or array; form/query values use JSON text.

{
  "type": "string",
  "format": "binary",
  "x-maximum-bytes": 20500000,
  "x-allowed-extensions": [
    "png",
    "jpg",
    "jpeg",
    "gif"
  ]
}
Send one file part using multipart/form-data, at most 20,500,000 bytes. The extension must match the actual image format.
crop JSON object/list No
An optional crop rectangle in the uploaded image's raw pixels.
View value format and limits

File uploads use multipart form data. Other structured values use a JSON object or array; form/query values use JSON text.

{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "x": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 8192.0
    },
    "y": {
      "type": "number",
      "minimum": 0.0,
      "maximum": 8192.0
    },
    "width": {
      "type": "number",
      "minimum": 0.0000001,
      "maximum": 8192.0
    },
    "height": {
      "type": "number",
      "minimum": 0.0000001,
      "maximum": 8192.0
    }
  },
  "x-member-name-comparison": "ordinal-ignore-case; duplicate case variants are rejected",
  "required": [
    "x",
    "y",
    "width",
    "height"
  ],
  "nullable": false,
  "x-maximum-depth": 2,
  "x-empty-create-means-omitted": true,
  "example": {
    "x": 0,
    "y": 0,
    "width": 125,
    "height": 94
  }
}
Supply x, y, width and height together. The rectangle must fit inside the image and have a 125:94 ratio. Omit it to use the largest centered rectangle of that ratio.
$result_format String No
By default, the response is a single object. Send array to get it inside a one-item array.
Allowed values: array | object
Idempotency-Key String No
An optional key for safely retrying the same image upload.
Send it as a header. Use 1 through 255 visible ASCII characters without spaces. Reuse the same key only for the same request; the API can return its saved response.

Uploading an image

  1. Retrieve the image list and check that the gallery has room for another image.
  2. Send one complete image as multipart/form-data. Add crop as a JSON form value if you want a specific crop.
  3. Use the returned image filename for later requests. POST does not issue a gallery revision.

Image preparation

The API prepares a JPEG using a 125:94 crop. Transparent areas use a white background, and small images may be enlarged. JPEG and static PNG are supported; for GIF, the first frame is kept. Animated PNG is not accepted.

The API uses raw image coordinates and does not apply EXIF rotation. Rotate the source before uploading when needed. Embedded profiles, thumbnails and unneeded metadata are ignored. The image must still decode successfully and match its checked format and dimensions.

Upload and processing limits

Each dimension must be at most 8,192 pixels. JPEG and PNG permit at most 24 million decoded pixels. GIF permits at most 64 frames and 24 million total canvas pixels across its frames. PNG decoded sample bytes must be at most 96 million; 16-bit PNGs can reach that limit sooner.

These processing limits are separate from the 20,500,000-byte upload limit. When image preparation is busy, the response is HTTP 429 with Retry-After. This is separate from the workspace's per-second request allowance. Uploads require an upgraded workspace plan.

Retrying an upload

Use Idempotency-Key when retrying the same upload. If the save outcome cannot be confirmed, inspect the current gallery before sending another upload. expected_revision is not supported on POST.

Image filenames and access

Treat the filenames returned by GET /v1/assets/images as opaque values. Use them with the selected Asset ID. Shared Assets' images are managed in the Asset's original workspace.

Editing an image on the website gives it a new image_filename. List the images again to get the current names.

Code Samples
# bash; inspect an error body instead of saving it as the requested file.
status=$(curl --silent --show-error -X POST "https://api.exhibitday.com/v1/assets/images" -H "Authorization: Bearer YOUR_API_KEY" --output response-body.tmp --write-out "%{http_code}" --form-string "asset_id=12345" --form "file=@asset-image.png;type=application/octet-stream")
if [ "$status" != 200 ]; then cat response-body.tmp; exit 1; fi
cat response-body.tmp

Example response

{
  "asset_id": 12345,
  "image_filename": "98765-12345-a1941c59-59cb-4b7d-b7a7-2f82f8bf84ab.jpg",
  "display_rank": 1,
  "image_last_update_timestamp": "2026-01-15T17:00:00Z"
}

Delete an Asset Image #

Method
DELETE
Endpoint

Deletes an existing Asset image.

Note: Inputs that do not apply to this operation, including the ignore-empty option, are ignored and reported in the X-API-Warnings response header.

Parameters
Name Type Required? Description Details
asset_id Number Yes
The ID of the Asset whose images to use, from Retrieve Assets (GET /v1/assets) or its create response.
image_filename String Yes
The image_filename from this Asset's image list.
Use the value exactly as returned. Image filenames stay the same when the order changes.
expected_revision String No
The record_revision returned by GET /v1/assets/images with $include_record_revision=true. Include it to avoid overwriting changes to its image gallery. Omit it to skip this check.

Removing an image

The image must still be in this Asset's gallery. An already-absent image returns HTTP 404. The remaining images keep their order.

The image disappears from the gallery when the save succeeds. Physical file removal follows later after reference checks. Other Asset content is unchanged.

Avoiding conflicting changes

Retrieve GET /v1/assets/images with $include_record_revision=true, then send its record_revision as expected_revision. This optional check covers the whole gallery.

If the gallery changed after that read, nothing changes and the response is HTTP 409. Retrieve the gallery again before deciding whether to retry. A successful request with this condition returns the resulting gallery revision.

Image filenames and access

Treat the filenames returned by GET /v1/assets/images as opaque values. Use them with the selected Asset ID. Shared Assets' images are managed in the Asset's original workspace.

Editing an image on the website gives it a new image_filename. List the images again to get the current names.

Code Samples
curl -X DELETE "https://api.exhibitday.com/v1/assets/images?asset_id=12345&image_filename=98765-12345-a1941c59-59cb-4b7d-b7a7-2f82f8bf84ab.jpg" -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "status_code": 200,
  "status": "OK",
  "message": "Asset image removed.",
  "errors": []
}

Reorder Asset Images #

Method
PATCH
Endpoint

Changes the order of an Asset's images.

Parameters
Name Type Required? Description Details
asset_id Number Yes
The ID of the Asset whose images to use, from Retrieve Assets (GET /v1/assets) or its create response.
image_filenames JSON object/list Yes
Every current image filename, once each, in the desired order.
View value format and limits

File uploads use multipart form data. Other structured values use a JSON object or array; form/query values use JSON text.

{
  "type": "array",
  "items": {
    "type": "string"
  },
  "maxItems": 5,
  "nullable": false,
  "x-maximum-depth": 2,
  "x-empty-create-means-omitted": false,
  "example": [
    "98765-12345-a1941c59-59cb-4b7d-b7a7-2f82f8bf84ab.jpg",
    "98765-12345-59f0a281-df13-4bc9-acf1-3c12c25b1d25.jpg"
  ]
}
Send a JSON array with at most five image filenames. An empty array is valid only for an empty gallery. Null or blank cannot clear images.
expected_revision String No
The record_revision returned by GET /v1/assets/images with $include_record_revision=true. Include it to avoid overwriting changes to its image gallery. Omit it to skip this check.

Reordering images

  1. Retrieve the current image list.
  2. Put every image_filename returned by GET /v1/assets/images in image_filenames, in the order you want.
  3. Submit the complete array. Use DELETE to remove an image.

When the order is unchanged

Sending the current order makes no change to images, timestamps, revision or history. Image filenames and file contents stay the same when the order changes.

Avoiding conflicting changes

Retrieve GET /v1/assets/images with $include_record_revision=true, then send its record_revision as expected_revision. This optional check covers the whole gallery.

If the gallery changed after that read, nothing changes and the response is HTTP 409. Retrieve the gallery again before deciding whether to retry. A successful request with this condition returns the resulting gallery revision.

Image filenames and access

Treat the filenames returned by GET /v1/assets/images as opaque values. Use them with the selected Asset ID. Shared Assets' images are managed in the Asset's original workspace.

Editing an image on the website gives it a new filename. List the images again to get the current names.

Code Samples
curl -X PATCH "https://api.exhibitday.com/v1/assets/images/order" -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"asset_id\":12345,\"image_filenames\":[\"98765-12345-a1941c59-59cb-4b7d-b7a7-2f82f8bf84ab.jpg\",\"98765-12345-59f0a281-df13-4bc9-acf1-3c12c25b1d25.jpg\"]}"

Example response

{
  "status_code": 200,
  "status": "OK",
  "message": "Asset images reordered.",
  "errors": []
}

Download an Asset Image #

Method
GET
Endpoint

Downloads an Asset image.

Parameters
Name Type Required? Description Details
asset_id Number Yes
The ID of the Asset whose images to use, from Retrieve Assets (GET /v1/assets) or its create response.
image_filename String Yes
The image_filename from this Asset's image list.
Use the value exactly as returned. Image filenames stay the same when the order changes.

Saving the download

Use the Asset ID and its current image_filename. The response contains the stored image file as an attachment. Older images keep their stored format.

A missing stored file returns HTTP 404. This download does not substitute the default Asset icon or support conditional or partial downloads.

Image filenames and access

Treat the filenames returned by GET /v1/assets/images as opaque values. Use them with the selected Asset ID. Shared Assets' images are managed in the Asset's original workspace.

Editing an image on the website gives it a new image_filename. List the images again to get the current names.

Files still being copied

If this file is still being copied, the download returns HTTP 409 with file_copy_pending. Try the download again in a few minutes.

Code Samples
# bash; inspect an error body instead of saving it as the requested file.
status=$(curl --silent --show-error -X GET "https://api.exhibitday.com/v1/assets/images/download?asset_id=12345&image_filename=98765-12345-a1941c59-59cb-4b7d-b7a7-2f82f8bf84ab.jpg" -H "Authorization: Bearer YOUR_API_KEY" --output response-body.tmp --write-out "%{http_code}")
if [ "$status" != 200 ]; then cat response-body.tmp; exit 1; fi
mv response-body.tmp 'asset-image.jpg'

Example response

File: asset-image.jpg
Content type: image/jpeg, image/png, image/gif, application/octet-stream
Note: The response body contains file bytes.