Skip to content
API Reference
/
/
Filter Images

Filter Images

Request

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:

{
  "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:

{
  "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
$filterstring

OData $filter expression — see the supported fields, operators and functions below

$orderbystring

OData $orderby expression — only the fields listed below are supported

$topinteger, (int64)

Maximum number of records to return (default: 100, max: 100)

$skipinteger, (int64)

Number of records to skip for pagination (default: 0)

Headers
X-API-KEYstringrequired

Tenant's API key (required)

GET
/images
curl -i -X GET \
  'https://api2.saleslayer.com/dam/images?%24filter=string&%24orderby=string&%24top=0&%24skip=0' \
  -H 'X-API-KEY: string'

Responses

OK

Bodyapplication/json
valueArray of objects or null(ImageDto)

The images in this page, at most $top (default and maximum 100).

@countinteger or null, (int64)

Total number of images matching the filter, ignoring $top/$skip.

Response
{
  "value": [
    { … }
  ],
  "@count": 0,
  "@readLink": "string",
  "@nextLink": "string"
}