Filtering and Sorting (V2)

This page describes how filtering and sorting work for our V2 API endpoints. V2 uses a different request shape than V1 — instead of query-string conditions[] parameters, V2 endpoints that support filtering and sorting take a JSON request body.

Request shape

A V2 query endpoint accepts a POST body shaped like this:

{
  "Filters": [
    { "Field": "ID", "Op": "Match", "Value": 12345 }
  ],
  "Sorting": [
    { "Field": "ID", "Direction": "DESC" }
  ],
  "Pagination": {
    "Page": 1,
    "PageSize": 50
  }
}

• Filters — an array of conditions. Each has a Field, an Op (operator), and a Value (or Values, for operators that take a list).
• Sorting — an array of { "Field": ..., "Direction": "ASC" | "DESC" }. You can pass more than one, and they're applied in order — for example, sort by one field and use a second field to break ties.
• Pagination — Page and PageSize.

Important: supported fields and operators are different for every endpoint

This is the part that has caused confusion, so it's worth calling out clearly: not every Field and not every Op works on every V2 endpoint. Each endpoint only accepts a specific, limited list of fields and operators — passing anything outside that list returns a 400 Invalid request body error.

Always check the specific endpoint's own reference page for its supported Field values, and use the table below for endpoints we've confirmed. If an endpoint's reference page doesn't clearly list its supported fields and operators, treat that as a documentation gap to flag — don't assume the general operator list below applies everywhere.

Confirmed: Timeline (POST /api/v2/timelines/query)

Supported Filters fields and operators:

No other fields can be used in Filters for this endpoint today — in particular, there is currently no way to filter Timeline records by a date field (CreatedOn or UpdatedOn).

Supported Sorting fields:

UpdatedOn is not a supported sort field today (this is what caused the 400 error that prompted this doc fix). You can combine multiple sort fields, e.g.:

"Sorting": [
  { "Field": "CreatedOn", "Direction": "ASC" },
  { "Field": "ID", "Direction": "ASC" }
]

That combination — sort by CreatedOn ascending, with ID as a tiebreaker — is the recommended approach today for anyone paging through Timeline records in a stable, repeatable order (for example, for incremental syncing).

(This page currently documents the Timeline endpoint. Add other V2 query endpoints here as their supported fields/operators get confirmed with engineering — don't guess or copy from Timeline's table, since each endpoint's supported list is different.)