Images API overview

Before you begin

Check out our general API overview to make sure you’re ready to get started with specific endpoints.

Use the Images API to automate the process of retrieving, uploading, and updating images in your Klaviyo account.

Use cases

Here are some use cases supported by the Images API:

Get all images in an account.
Get an image by image ID.
Import an image from a URL or data URI.
Update an image by image ID.
Upload an image from a file.

📘
Create and upload images to your Klaviyo account using AI with our Images API.

Data model

A retrieved image has the following:

id

The ID of the image.
attributes
- name
  
  A name for the image. Defaults to the filename if not provided. If the name matches an existing image, a suffix will be added.
- image_url
  
  An existing image URL to import the image from.
- format
  
  The type of file (e.g., jpeg). Supported formats include jpeg, png, and gif.
- size
  
  The size of the image in bytes. Maximum file size is 5 MB.
- hidden
  
  Whether the image is shown in the asset library (defaults to false).
- updated_at
  
  The timestamp of when the image was last updated.

Upload an image

Check out the examples below on using the Images API to import an image from a URL or file.

Upload an image from URL

To upload an image from a URL, you’ll need to include the image URL in your request payload to Upload Image From URL. The request and response should look something like this:

{
   "data": {
       "type": "image",
       "attributes": {
           "import_from_url": "https://via.placeholder.com/150",
           "name": "Blue T-Shirt",
           "hidden": false
       }
   }
}

{
    "data": {
        "type": "image",
        "id": "193828341",
        "attributes": {
            "name": "Blue T-Shirt",
            "image_url": "https://via.placeholder.com/150",
            "format": "jpeg",
            "size": 32335,
            "hidden": false,
            "updated_at": "2025-01-16T21:44:39.021934+00:00"
        },
        "links": {
            "self": "https://a.klaviyo.com/api/images/193828341/"
        }
    },
    "links": {
        "self": "https://a.klaviyo.com/api/images"
    }
}

Upload an image from file

To upload an image from a file, use the Upload Image From File endpoint. Here's an example request and response:

curl --request POST \
     --url https://a.klaviyo.com/api/image-upload \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'content-type: multipart/form-data' \
     --header 'revision: 2025-01-15' \
     --form hidden=false \
     --form file='@baseballcap.jpeg' \
     --form 'name=baseball cap'

{
    "data": {
        "type": "image",
        "id": "195062861",
        "attributes": {
            "name": "baseball cap",
            "image_url": "https://d3k81ch9hvuctc.cloudfront.net/company/your_company_id/images/141a0b0b-3f5f-4798-a4b5-61f0785b7958.jpeg",
            "format": "jpeg",
            "size": 9634,
            "hidden": false,
            "updated_at": "2025-01-16T18:06:14.845463+00:00"
        },
        "links": {
            "self": "https://a.klaviyo.com/api/images/195062861/"
        }
    },
    "links": {
        "self": "https://a.klaviyo.com/api/image-upload"
    }
}

Here's how the example image appears in Klaviyo:

Get Image(s)

The Get Image(s) endpoints are useful for fetching images from your Klaviyo account. When making a Get Image or Get Images request, here’s an example of how it could look:

curl --request GET \
     --url 'https://a.klaviyo.com/api/images?page[size]=20' \
     --header 'Authorization: Klaviyo-API-Key your-private-api-key' \
     --header 'accept: application/vnd.api+json' \
     --header 'revision: 2025-01-15'

{
   "data": [
       {
           "type": "image",
           "id": "167135588",
           "attributes": {
               "name": "test",
               "image_url": "https://via.placeholder.com/150",
               "format": "jpeg",
               "size": 1143579,
               "hidden": false,
               "updated_at": "2024-09-03T17:23:19+00:00"
           },
           "links": {
               "self": "https://a.klaviyo.com/api/images/167135588/"
           }
       }
   ],
   "links": {
       "self": "https://a.klaviyo.com/api/images",
       "next": null,
       "prev": null
   }
}

Querying images

Querying images with the Images API can help you achieve many use cases, e.g., fetching a list of images with a size greater than 1 MB and less than 5 MB. Check out the supported query parameters below and test them out with our latest Postman collection. Note that support for given operators and fields is endpoint-specific. Review the API reference documentation for more information on allowed fields and query operators.

Parameter	Description	Query example
`filter`	Retrieve a subset of catalog resources, e.g., all jpeg images. Learn about the filter query parameter.	`GET /api/images?filter=equals(format,"jpeg")`
`sort`	Sort images, e.g., by size (smallest to largest). Learn about the sort query parameter.	`GET /api/images?sort=size`
`fields`	Request for only specified image data, e.g., image URL. Learn more about sparse fieldsets.	`GET /api/images?fields[image]=image_url,format`

Before you begin

Use cases

📘

Data model

Upload an image

Upload an image from URL

Upload an image from file

Get Image(s)

Querying images

Additional resources