# 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:33Z",
      "fileType": "jpg",
      "createdOn": "2024-04-05T08:44:33Z",
      "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`

## Dates
`createdOn` and `modifiedOn` are returned in UTC, as ISO 8601 with a `Z` suffix
(e.g. `2024-04-05T08:44:33Z`). Date values in `$filter` are compared as UTC instants: send them
in ISO 8601 with a `Z` suffix, e.g. `$filter=modifiedOn gt 2024-04-05T08:44:33Z`.
## 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 (Parameter 'propertyName')",
        "AttemptedValue": null
      }
    ]
  }
}
```

Endpoint: GET /images
Version: 2.0.0

## Description:

  - `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:33Z",
      "fileType": "jpg",
      "createdOn": "2024-04-05T08:44:33Z",
      "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`

  - `Dates` ()
    `createdOn` and `modifiedOn` are returned in UTC, as ISO 8601 with a `Z` suffix
(e.g. `2024-04-05T08:44:33Z`). Date values in `$filter` are compared as UTC instants: send them
in ISO 8601 with a `Z` suffix, e.g. `$filter=modifiedOn gt 2024-04-05T08:44:33Z`.

  - `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 (Parameter 'propertyName')",
        "AttemptedValue": null
      }
    ]
  }
}
```

## 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)

## Header parameters:

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

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `value` (array)
    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)
    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)
    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)
    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)
    When the image was created. Null for images predating creation-date tracking.

  - `value.tags` (array)
    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)
    URL of the original, full-size image. Empty until processing has run.

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

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

  - `value.thumbnailPreviewUrl` (string)
    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)
    Total number of images matching the filter, ignoring `$top`/`$skip`.

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

  - `@nextLink` (string)
    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:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `validationFailures` (object)

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 401 fields (application/json):

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

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

## Response 403:

  - `403` (unknown)
    Forbidden

## Response 403 fields (application/json):

  - `message` (string)

  - `request_id` (string)

## Response 500:

  - `500` (unknown)
    Internal Server Error

## Response 500 fields (application/json):

  - `error` (string)

  - `details` (any)

