Pagination

POST /properties exposes two modes via the paginationType discriminator (enum "PAGE" or "CURSOR", default "PAGE").

paginationType: "PAGE" — classic offset

Simple and readable, but may duplicate or skip items if data shifts between pages.

{
  "paginationType": "PAGE",
  "page": 1,
  "size": 20,
  "criteria": {
    "property": { "type": { "in": ["FLAT"] } }
  }
}

Increment page until meta.hasNextPage === false.

paginationType: "CURSOR" — stable cursor

Recommended for scraping / export / long lists. Stable even if items are inserted between calls.

First request

Omit cursor (or send null):

{
  "paginationType": "CURSOR",
  "size": 50,
  "criteria": {
    "property": { "type": { "in": ["FLAT"] } }
  }
}

Response

{
  "data": [ /* 50 Property resources */ ],
  "meta": {
    "totalItems": 4231,
    "hasNextPage": true,
    "cursor": "eyJzb3J0IjpbMTc3ODg0NDY0MzAwMCwiMDE5Z...",
    "pagination": {
      "type": "CURSOR",
      "size": 50,
      "nextRequestBody": { /* the next request, ready to send */ }
    }
  },
  "links": { "self": "/properties" },
  "included": [ /* Listing, Publisher, PropertyPublisher, Source */ ]
}

Next page

Echo the meta.cursor value from the previous response as-is:

{
  "paginationType": "CURSOR",
  "size": 50,
  "cursor": "eyJzb3J0IjpbMTc3ODg0NDY0MzAwMCwiMDE5Z...",
  "criteria": {
    "property": { "type": { "in": ["FLAT"] } }
  }
}

Loop until meta.hasNextPage === false. The cursor is opaque — do not try to parse it, just echo it back.

Count without fetching properties

To learn how many properties match your criteria without receiving them — a counter beside a filter, a volume estimate before an export — send size: 0:

{
  "size": 0,
  "criteria": {
    "property": { "type": { "in": ["FLAT"] } }
  }
}

The response carries no property; the count is in meta.totalItems:

{
  "data": [],
  "meta": {
    "totalItems": 243
    /* … */
  }
}

• The count is read in JSON:API format (default). With Accept: application/json, the response is a bare array, hence empty: it does not carry the count.
• In PAGE mode, meta.totalItems is capped at 10,000.

Limits

• size: from 0 to 100 per request (default 10). 0 returns the result count only.
• meta.totalItems is always returned, useful for displaying a total even in CURSOR mode.
• With Accept: application/json (flat format), POST /properties returns a bare array without totalItems, hasNextPage or cursor: paginate in JSON:API format. See Response format.
• page is ignored in CURSOR mode; cursor is ignored in PAGE mode.