Skip to content
/Files

Filter Files

Request

Returns a paginated collection of the tenant's non-image files (documents, spreadsheets, archives, …), 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 files are under value, never at the top level:

{
  "value": [
    {
      "reference": "product-datasheet.pdf",
      "numLinks": 3,
      "status": "Ok",
      "modifiedOn": "2024-04-05T08:44:33",
      "fileType": "pdf",
      "createdOn": "2024-04-05T08:44:33",
      "tags": ["datasheets", "catalog"],
      "url": "https://cdn.example.com/product-datasheet.pdf",
      "sizeInBytes": 102400
    }
  ],
  "@count": 137,
  "@readLink": "https://api2.saleslayer.com/dam/files?$top=50",
  "@nextLink": "https://api2.saleslayer.com/dam/files?$top=50&$skip=50"
}

Notes on the payload:

  • status tells you whether the file is usable yet — see the status values below.
  • url and sizeInBytes come from the stored metadata and are empty / 0 until processing has recorded them.
  • 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:

reference, numLinks, status, modifiedOn, fileType, createdOn

Field names are case-insensitive. Every other field — including tags, url and sizeInBytes — 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

Results are not filtered by status, so files in any of these states can be returned. Filter on status explicitly if you only want usable files.

Examples

GET /files?$filter=fileType eq 'pdf'
GET /files?$filter=status eq 'Ok'
GET /files?$filter=fileType eq 'csv' and status eq 'Ok'
GET /files?$filter=status in ('Ok', 'Re')
GET /files?$filter=contains(reference, 'datasheet')
GET /files?$filter=startswith(reference, 'product-') and numLinks gt 0
GET /files?$orderby=createdOn desc
GET /files?$filter=fileType ne 'txt'&$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: 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
/files
curl -i -X GET \
  'https://api2.saleslayer.com/dam/files?%24filter=string&%24orderby=string&%24top=0&%24skip=0' \
  -H 'X-API-KEY: string'

Responses

OK

Bodyapplication/json
valueArray of objects or null(FileDto)

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

@countinteger or null, (int64)

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

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