Paging, filtering and sorting

Lists that can grow large are paged. A paged endpoint takes the same three query parameters and returns the same response shape. Other list endpoints return the whole list as a JSON array.

Parameters

Parameter	Default	Rules
page	1	The page number, from 1.
pageSize	50	Items per page, from 1 to 200.
sort	Per endpoint	One field from the endpoint’s list of sortable fields, case-insensitive. Prefix it with - for descending order.

An out-of-range value or a field that can’t be sorted on gets a 400 validation error.

You can sort by one field at a time. jtWMS adds tie-breakers to every sort, so the order is stable and consecutive pages never overlap or skip an item while the data is unchanged.

curl "https://<your-jtwms-host>/api/v1/products?page=2&pageSize=100&sort=-updatedAt&status=Active" \
  -H "X-Api-Key: <api-key>"

Response

{
  "items": [
    { "id": "8c1f4b9e-2d3a-4f5b-9c6d-7e8f9a0b1c2d", "sku": "PAL-0042", "name": "Pallet wrap" }
  ],
  "page": 2,
  "pageSize": 100,
  "totalCount": 1342
}

Member	Meaning
items	The items on this page. Empty when page is past the last page.
page	The page returned.
pageSize	The page size used.
totalCount	The number of items that match the filters, across all pages.

The number of pages is ceil(totalCount / pageSize). Paging is by offset: if items are added or removed while you page, an item can move between pages. To copy a whole data set consistently, use a snapshot endpoint where one exists, such as GET /api/v1/snapshot for warehouse configuration or GET /api/v1/products/snapshot for the catalog.

Paged endpoints

Endpoint	Sortable fields (default first)	Filters
GET /api/v1/products	sku, name, createdAt, updatedAt	search (SKU or name contains, or exact barcode), status (Active, Inactive), category, velocityClass (A, B, C)
GET /api/v1/facilities/{facilityId}/locations	code, ownerKind, nodeType	ownerKind (Storage, Equipment), nodeType, search (code contains)
GET /api/v1/audit-entries	-occurredAt	entityType, entityId, from, to (ISO 8601)
GET /api/v1/team/audit-entries	-occurredAt	entityType, entityId, from, to (ISO 8601)
GET /api/v1/api-keys	-createdAt, name	None
GET /api/v1/webhook-subscriptions	createdAt, url	status (Active, Inactive)
GET /api/v1/webhook-subscriptions/{id}/deliveries	-createdAt, nextAttemptAt	status (Pending, Sending, Delivered, DeadLettered)

The default sort is the first field listed, in the direction shown: -occurredAt means newest first. The search, category, ownerKind and nodeType filters ignore case. Filters combine: an item must match all of them.

Every other list endpoint, such as GET /api/v1/facilities or a facility’s zone profiles, returns a JSON array of every item, with no paging parameters and no envelope.