Product Images API

Upload, list, and delete images for a product. Image uploads use
multipart/form-data.

Endpoints

• List Product Images - GET /api/v1/products/{id}/images/
• Upload Product Images - POST /api/v1/products/{id}/images/
• Delete Product Image - DELETE /api/v1/products/{id}/images/{image_id}/

List Product Images

Retrieve all images for a product. This endpoint is not paginated.

Endpoint: GET /api/v1/products/{id}/images/

Permission Required: Read

Request

curl -X GET "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/images/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "img_d0b6fmv28q6vn14peun0",
      "url": "/images/abc123_large.webp",
      "alt_text": "Front of the t-shirt",
      "width": 1200,
      "height": 1200,
      "format": "webp",
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:00:00Z"
    }
  ]
}

The url is relative to the storefront origin.

Upload Product Images

Upload one or more images for a product. Send the images as files in a
multipart/form-data body. Every file part is stored, so you can include
several images in a single request.

Endpoint: POST /api/v1/products/{id}/images/

Permission Required: Write

Limits

• The total request body must be 5 MiB or smaller.
• Supported formats depend on the image decoder. Common web formats such as
  JPEG, PNG, GIF, and WebP are accepted.

Request

curl -X POST "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/images/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -F "file=@front.jpg" \
  -F "file=@back.jpg"

Response

Status: 201 Created

{
  "data": [
    {
      "id": "img_d0b6fmv28q6vn14peun0",
      "url": "/images/abc123_large.webp",
      "alt_text": null,
      "width": 1200,
      "height": 1200,
      "format": "webp",
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:00:00Z"
    }
  ]
}

Error Responses

Invalid multipart form

Status: 400 Bad Request

{
  "error": "Invalid input",
  "code": "INVALID_FIELD"
}

Request too large

Status: 500 Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Delete Product Image

Delete an image from a product.

Endpoint: DELETE /api/v1/products/{id}/images/{image_id}/

Permission Required: Write

Request

curl -X DELETE "https://studio.easel.engineering/api/v1/products/pro_d0b6fmv28q6vn14peun0/images/img_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 204 No Content

Error Responses

Image not found

Status: 404 Not Found

{
  "error": "Resource not found",
  "code": "NOT_FOUND"
}

Image Object

Fields