Klaviyo
Klaviyo Images API

images
Documentation GitHub OpenAPI
OpenAPI Specification

openapi: 3.0.2
info:
  title: Klaviyo Accounts Images API
  version: '2026-04-15'
  description: The Klaviyo REST API. Please visit https://developers.klaviyo.com for more details.
  contact:
    name: Klaviyo Developer Experience Team
    email: developers@klaviyo.com
    url: https://developers.klaviyo.com
  termsOfService: https://www.klaviyo.com/legal/api-terms
  license:
    name: License
    url: https://www.klaviyo.com/legal
servers:
- url: https://a.klaviyo.com
  description: Production
security:
- Klaviyo-API-Key: []
tags:
- name: Images
  description: images
paths:
  /api/images:
    get:
      operationId: get_images
      summary: Get Images
      description: 'Get all images in an account.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`


        **Scopes:**

        `images:read`'
      parameters:
      - name: fields[image]
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - format
            - hidden
            - image_url
            - name
            - size
            - updated_at
        explode: false
      - name: filter
        in: query
        description: 'For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#filtering<br>Allowed field(s)/operator(s):<br>`id`: `any`, `equals`<br>`updated_at`: `greater-or-equal`, `greater-than`, `less-or-equal`, `less-than`<br>`format`: `any`, `equals`<br>`name`: `any`, `contains`, `ends-with`, `equals`, `starts-with`<br>`size`: `greater-or-equal`, `greater-than`, `less-or-equal`, `less-than`<br>`hidden`: `any`, `equals`'
        schema:
          type: string
          example: equals(id,'7')
      - name: page[cursor]
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#pagination
        required: false
        schema:
          type: string
      - name: page[size]
        in: query
        description: 'Default: 20. Min: 1. Max: 100.'
        required: false
        schema:
          type: integer
          default: 20
          maximum: 100
          minimum: 1
      - name: sort
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sorting
        schema:
          type: string
          enum:
          - format
          - -format
          - id
          - -id
          - name
          - -name
          - size
          - -size
          - updated_at
          - -updated_at
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetImageResponseCollection'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Images
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 10/s
        steady: 150/m
      x-klaviyo-scopes:
      - images:read
    post:
      operationId: upload_image_from_url
      summary: Upload Image From URL
      description: 'Import an image from a url or data uri.


        If you want to upload an image from a file, use the Upload Image From File endpoint instead.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `100/m`<br>Daily: `100/d`


        **Scopes:**

        `images:write`'
      parameters:
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/ImageCreateQuery'
      responses:
        '201':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PostImageResponse'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Images
      x-klaviyo-operation-aliases:
      - create_image
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 3/s
        steady: 100/m
        daily: 100/d
      x-klaviyo-scopes:
      - images:write
  /api/images/{id}:
    get:
      operationId: get_image
      summary: Get Image
      description: 'Get the image with the given image ID.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`


        **Scopes:**

        `images:read`'
      parameters:
      - name: id
        in: path
        description: The ID of the image
        required: true
        schema:
          description: The ID of the image
          type: string
          example: '7'
      - name: fields[image]
        in: query
        description: For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#sparse-fieldsets
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - format
            - hidden
            - image_url
            - name
            - size
            - updated_at
        explode: false
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/GetImageResponse'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Images
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 10/s
        steady: 150/m
      x-klaviyo-scopes:
      - images:read
    patch:
      operationId: update_image
      summary: Update Image
      description: 'Update the image with the given image ID.<br><br>*Rate limits*:<br>Burst: `10/s`<br>Steady: `150/m`


        **Scopes:**

        `images:write`'
      parameters:
      - name: id
        in: path
        description: The ID of the image
        required: true
        schema:
          description: The ID of the image
          type: string
          example: '7'
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      requestBody:
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/ImagePartialUpdateQuery'
      responses:
        '200':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PatchImageResponse'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Images
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 10/s
        steady: 150/m
      x-klaviyo-scopes:
      - images:write
  /api/image-upload:
    post:
      operationId: upload_image_from_file
      summary: Upload Image From File
      description: 'Upload an image from a file.


        If you want to import an image from an existing url or a data uri, use the Upload Image From URL endpoint instead.<br><br>*Rate limits*:<br>Burst: `3/s`<br>Steady: `100/m`<br>Daily: `100/d`


        **Scopes:**

        `images:write`'
      parameters:
      - name: revision
        in: header
        description: 'API endpoint revision (format: YYYY-MM-DD[.suffix])'
        required: true
        schema:
          type: string
          default: '2026-04-15'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImageUploadQuery'
      responses:
        '201':
          description: Success
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/PostImageResponse'
        4XX:
          $ref: '#/components/responses/ClientError'
        5XX:
          $ref: '#/components/responses/ServerError'
      tags:
      - Images
      x-klaviyo-operation-aliases:
      - create_image_upload
      x-klaviyo-pre-release: None
      x-klaviyo-ratelimit:
        burst: 3/s
        steady: 100/m
        daily: 100/d
      x-klaviyo-scopes:
      - images:write
components:
  schemas:
    ImagePartialUpdateQueryResourceObject:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ImageEnum'
        id:
          description: The ID of the image
          type: string
          example: '7'
        attributes:
          type: object
          properties:
            name:
              description: A name for the image.
              type: string
              nullable: true
            hidden:
              description: If true, this image is not shown in the asset library.
              type: boolean
              nullable: true
      required:
      - type
      - id
      - attributes
    ImageCreateQueryResourceObject:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ImageEnum'
        attributes:
          type: object
          properties:
            name:
              description: A name for the image.  Defaults to the filename if not provided.  If the name matches an existing image, a suffix will be added.
              type: string
              nullable: true
            import_from_url:
              description: 'An existing image url to import the image from. Alternatively, you may specify a base-64 encoded data-uri (`data:image/...`). Supported image formats: jpeg,png,gif. Maximum image size: 5MB.'
              type: string
              example: https://www.example.com/example.jpg
            hidden:
              description: If true, this image is not shown in the asset library.
              type: boolean
              default: false
              nullable: true
          required:
          - import_from_url
      required:
      - type
      - attributes
    ObjectLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
      required:
      - self
    ImageResponseObjectResource:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ImageEnum'
        id:
          description: The ID of the image
          type: string
          example: '7'
        attributes:
          type: object
          properties:
            name:
              type: string
            image_url:
              type: string
            format:
              type: string
            size:
              type: integer
            hidden:
              type: boolean
            updated_at:
              type: string
              format: date-time
              example: '2022-11-08T00:00:00+00:00'
          required:
          - name
          - image_url
          - format
          - size
          - hidden
          - updated_at
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - type
      - id
      - attributes
      - links
    ImageUploadQuery:
      type: object
      properties:
        file:
          description: 'The image file to upload. Supported image formats: jpeg,png,gif. Maximum image size: 5MB.'
          type: string
          format: binary
        name:
          description: A name for the image.  Defaults to the filename if not provided.  If the name matches an existing image, a suffix will be added.
          type: string
        hidden:
          description: If true, this image is not shown in the asset library.
          type: boolean
          default: false
      required:
      - file
    CollectionLinks:
      type: object
      properties:
        self:
          type: string
          format: uri
        first:
          type: string
          format: uri
        last:
          type: string
          format: uri
        prev:
          type: string
          format: uri
        next:
          type: string
          format: uri
      required:
      - self
    PostImageResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/ImageEnum'
            id:
              description: The ID of the image
              type: string
              example: '7'
            attributes:
              type: object
              properties:
                name:
                  type: string
                image_url:
                  type: string
                format:
                  type: string
                size:
                  type: integer
                hidden:
                  type: boolean
                updated_at:
                  type: string
                  format: date-time
                  example: '2022-11-08T00:00:00+00:00'
              required:
              - name
              - image_url
              - format
              - size
              - hidden
              - updated_at
            links:
              $ref: '#/components/schemas/ObjectLinks'
          required:
          - type
          - id
          - attributes
          - links
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    GetImageResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ImageResponseObjectResource'
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    ImagePartialUpdateQuery:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ImagePartialUpdateQueryResourceObject'
      required:
      - data
    ImageEnum:
      type: string
      enum:
      - image
    ImageCreateQuery:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/ImageCreateQueryResourceObject'
      required:
      - data
    PatchImageResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            type:
              $ref: '#/components/schemas/ImageEnum'
            id:
              description: The ID of the image
              type: string
              example: '7'
            attributes:
              type: object
              properties:
                name:
                  type: string
                image_url:
                  type: string
                format:
                  type: string
                size:
                  type: integer
                hidden:
                  type: boolean
                updated_at:
                  type: string
                  format: date-time
                  example: '2022-11-08T00:00:00+00:00'
              required:
              - name
              - image_url
              - format
              - size
              - hidden
              - updated_at
            links:
              $ref: '#/components/schemas/ObjectLinks'
          required:
          - type
          - id
          - attributes
          - links
        links:
          $ref: '#/components/schemas/ObjectLinks'
      required:
      - data
    GetImageResponseCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ImageResponseObjectResource'
        links:
          $ref: '#/components/schemas/CollectionLinks'
      required:
      - data
  responses:
    ClientError:
      description: Client Error
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - code
                  - title
                  - detail
                  properties:
                    id:
                      type: string
                    code:
                      type: string
                    title:
                      type: string
                    detail:
                      type: string
                    source:
                      type: object
                      properties:
                        pointer:
                          type: string
                        parameter:
                          type: string
            required:
            - errors
    ServerError:
      description: Server Error
      content:
        application/vnd.api+json:
          schema:
            type: object
            properties:
              errors:
                type: array
                items:
                  type: object
                  required:
                  - id
                  - code
                  - title
                  - detail
                  properties:
                    id:
                      type: string
                    code:
                      type: string
                    title:
                      type: string
                    detail:
                      type: string
                    source:
                      type: object
                      properties:
                        pointer:
                          type: string
                        parameter:
                          type: string
            required:
            - errors
  securitySchemes:
    Klaviyo-API-Key:
      type: apiKey
      in: header
      name: Authorization
      description: Private key authentication for /api/ endpoints is performed by setting the `Authorization` header to `Klaviyo-API-Key your-private-api-key`<br>For more information please visit https://developers.klaviyo.com/en/v2026-04-15/reference/api-overview#authentication
      x-default: Klaviyo-API-Key your-private-api-key
x-readme:
  explorer-enabled: false
  proxy-enabled: true
  samples-enabled: true
Klaviyo Images API

Documentation

Specifications

Other Resources

OpenAPI Specification
