# Filter Images

Returns a paginated collection of the tenant's images, filtered and sorted using OData query options ($filter, $orderby, $top, $skip).
            
## Authentication
            
Requires a valid API key in the X-API-KEY header.
            
## Response (200 OK)
            
The page is wrapped in the house collection envelope — the images are under value, never at the
top level:
            
json
{
  "value": [
    {
      "id": 42,
      "reference": "product-main-front.jpg",
      "numLinks": 3,
      "status": "Ok",
      "modifiedOn": "2024-04-05T08:44:33",
      "fileType": "jpg",
      "createdOn": "2024-04-05T08:44:33",
      "tags": ["animales", "mascotas"],
      "originalUrl": "https://cdn.example.com/product-main-front.jpg",
      "thumbnailUrl": "https://cdn.example.com/product-main-front_TH.jpg",
      "thumbnailMediumUrl": "https://cdn.example.com/product-main-front_THM.jpg",
      "thumbnailPreviewUrl": "https://cdn.example.com/product-main-front_THP.jpg",
      "width": 800,
      "height": 600,
      "sizeInBytes": 102400
    }
  ],
  "@count": 137,
  "@readLink": "https://api2.saleslayer.com/dam/images?$top=50",
  "@nextLink": "https://api2.saleslayer.com/dam/images?$top=50&$skip=50"
}

            
Notes on the payload:
            
- status tells you whether the image is usable yet — see the status values documented on
  GET /images. A freshly created or substituted image is Up until the worker finishes.
- width, height and sizeInBytes come from the stored metadata and are 0 until processing
  has recorded them; the thumbnail URLs are empty until the renditions exist.
- tags is stored as a comma-separated string, so a tag that itself contains a comma comes back
  split into several tags.
- @count is the total number of matches, ignoring $top/$skip.
- @readLink is the canonical URL of this collection — this request, echoed back.
- @nextLink is the URL of the next page and is omitted on the last page.
            
The @-prefixed hypermedia links (@readLink, @nextLink) are only emitted when hypermedia
enrichment is configured for the deployment; @count is always present. Where the links are
absent, page forward by incrementing $skip yourself until fewer than $top items come back.
            
## Supported fields
            
Only these fields can be used in $filter and $orderby:
            
id, reference, numLinks, status, modifiedOn, fileType, createdOn
            
Field names are case-insensitive. Every other field of the response — including tags,
width, height, sizeInBytes and the URL fields — is not queryable: naming one in
$filter or $orderby returns 400. $orderby honours only the first sort expression.
            
$select and $expand are not supported and are ignored.
            
## Supported operators and functions
            
- Comparison: eq, ne, gt, ge, lt, le
- Logical: and, or, not
- Sets: in
- Functions: contains, startswith, endswith
            
## Status field values
            
- Vd - Void (not yet started processing)
- Up - Updating (being uploaded/updated)
- Ok - Processed correctly (ready to use)
- Re - Reprocessing
- Er - Error (processing failed)
- Dv - Deleted/void (no longer counts towards the tenant's image-library quota)
            
Results are not filtered by status, so images in any of these states can be returned. Filter on
status explicitly if you only want usable images.
            
## Examples
            

GET /images?$filter=fileType eq 'jpg'
GET /images?$filter=status eq 'Ok'
GET /images?$filter=fileType eq 'png' and status eq 'Ok'
GET /images?$filter=status in ('Ok', 'Re')
GET /images?$filter=contains(reference, 'product')
GET /images?$filter=startswith(reference, 'product-') and numLinks gt 0
GET /images?$orderby=createdOn desc
GET /images?$filter=fileType ne 'gif'&$orderby=numLinks desc&$skip=0&$top=50

            
## Error Responses
            
- 400 Bad Request: Invalid $filter syntax, a field that is not queryable in $filter or
  $orderby, a negative $skip, or a $top that is not between 1 and 100
- 401 Unauthorized: Missing or invalid API key. Returned by the API gateway as
  { "message": "Unauthorized", "request_id": "d8aafa5b8f3e400b60bea0123dd33317" }
- 403 Forbidden: The API key does not have read permissions for this operation. Same body
  shape as the 401
- 500 Internal Server Error: Technical error (e.g. database unavailable)
            
A 400 uses the shared validation envelope, keyed by the offending parameter:
            
json
{
  "validationFailures": {
    "$orderby": [
      {
        "PropertyName": "$orderby",
        "ErrorMessage": "Ordering by 'tags' is not supported. Supported fields: id, reference, numlinks, status, modifiedon, filetype, createdon",
        "AttemptedValue": null
      }
    ]
  }
}

Endpoint: GET /images
Version: 2.0.0

## Header parameters:

  - `X-API-KEY` (string, required)
    Tenant's API key (required)

## Query parameters:

  - `$filter` (string)
    OData $filter expression — see the supported fields, operators and functions below

  - `$orderby` (string)
    OData $orderby expression — only the fields listed below are supported

  - `$top` (integer)
    Maximum number of records to return (default: 100, max: 100)

  - `$skip` (integer)
    Number of records to skip for pagination (default: 0)

## Response 200 fields (application/json):

  - `value` (array,null)
    The images in this page, at most $top (default and maximum 100).

  - `value.id` (integer)
    Internal numeric identifier. Not stable as a public key — address images by reference.

  - `value.reference` (string,null)
    The image's filename, unique per tenant. This is the public key used to address the image and the
value entities use to reference it.

  - `value.numLinks` (integer)
    Number of entities (products, variants, categories, …) currently using this image.

  - `value.status` (string,null)
    Processing status: Vd (void), Up (uploading/updating), Ok (ready to use),
Re (reprocessing), Er (processing failed) or Dv (deleted). Only Ok
guarantees the renditions exist.

  - `value.modifiedOn` (string)
    When the image was last modified.

  - `value.fileType` (string,null)
    File extension of the image, without the dot (e.g. jpg, png). Derived from the
filename, not from the served Content-Type.

  - `value.createdOn` (string,null)
    When the image was created. Null for images predating creation-date tracking.

  - `value.tags` (array,null)
    Tags assigned to the image. Stored as a comma-separated string, so a tag containing a comma is
read back as several tags. Not usable in $filter or $orderby.

  - `value.originalUrl` (string,null)
    URL of the original, full-size image. Empty until processing has run.

  - `value.thumbnailUrl` (string,null)
    URL of the small thumbnail rendition. Empty until processing has generated it.

  - `value.thumbnailMediumUrl` (string,null)
    URL of the medium thumbnail rendition. Empty until processing has generated it.

  - `value.thumbnailPreviewUrl` (string,null)
    URL of the preview thumbnail rendition. Empty until processing has generated it.

  - `value.width` (integer)
    Width of the image in pixels; 0 until processing has recorded it. Not usable in
$filter or $orderby.

  - `value.height` (integer)
    Height of the image in pixels; 0 until processing has recorded it. Not usable in
$filter or $orderby.

  - `value.sizeInBytes` (integer)
    Size of the image file in bytes; 0 until processing has recorded it. Not usable in
$filter or $orderby.

  - `@count` (integer,null)
    Total number of images matching the filter, ignoring $top/$skip.

  - `@readLink` (string,null)
    Canonical URL of this collection — this request, echoed back. Present only when hypermedia
enrichment is enabled.

  - `@nextLink` (string,null)
    URL of the next page, omitted on the last page. Present only when hypermedia enrichment is
enabled; otherwise page forward by incrementing $skip yourself.

## Response 400 fields (application/json):

  - `validationFailures` (object,null)

## Response 401 fields (application/json):

  - `message` (string,null)
    Error description, e.g. Unauthorized.

  - `request_id` (string,null)
    Gateway request identifier, to quote when contacting support.

## Response 403 fields (application/json):

  - `message` (string,null)

  - `request_id` (string,null)

## Response 500 fields (application/json):

  - `error` (string,null)

  - `details` (any,null)