Reading resources

fields — the shape of the response

Without fields, a resource is represented by its scalar values: its own data plus, for every reference it holds, the value that identifies it — assigneeId for a contact, statusName for a status. Related objects are never embedded by default.

fields selects explicitly, and it drives the database read as well as the response, so asking for less is genuinely cheaper:

Selection	Response
fields=subject,createdAt	id, subject, createdAt
fields=assignee	id plus the assignee's scalar values
fields=assignee.firstName,assignee.lastName	id plus exactly those two
fields=labels(limit=5;sort=name)	id plus the first five labels by name

Anything listed as a property of the resource's schema can be selected. Rules worth knowing:

• id is returned first at every level, whether or not it was asked for.
• A relation selected without sub-fields yields its own scalar values — the same rule that shapes the resource itself.
• Fields are returned in the order they were requested.
• A collection accepts (limit=…;offset=…;sort=…); without a limit it returns at most 50 entries, and never more than 100.
• An unknown field name is answered with 400.

filter — a JSON expression

A predicate is {"field": …, "op": …, "value": …}; and, or and not nest them. A field may be a dotted path into a filterable relation. Which fields a resource accepts is documented per endpoint; an unknown one is answered with 400.

{"and":[{"field":"status.name","op":"eq","value":"in_progress"},
        {"field":"createdAt","op":"gte","value":"2026-03-01T00:00:00Z"}]}

Operators: eq, neq, contains, startsWith, endsWith, doesNotContain, in, notIn, gt, gte, lt, lte, isNull, isNotNull.

search — free text

The term is used as a whole — leading and trailing spaces are trimmed, nothing else is split off — and matched case-insensitively as a substring. Which fields it reaches is decided per resource and documented at the endpoint; it commonly includes related people, so searching for a name finds the tickets of that person. A resource that does not offer a search ignores the parameter.

sort — ordered terms

Comma-separated field:direction, direction defaults to asc: sort=priority.level:desc,createdAt. A field may be relation.field for a to-one relation. Results always receive id as a final tie-breaker, so paging stays stable.

offset and limit

limit has to be between 1 and 100 and defaults to 100. count in the response is the total number of matching rows, not the size of the page — use it to drive paging.