Raytha API filtering: filter, orderBy, search and paging

The list endpoint for content items accepts an OData-style filter, an orderBy, a search string and paging parameters. This page lists exactly what the filter language accepts, how each field type behaves, and what the errors say.

A filter in one request

Fetch the ten newest published posts in the news category.

curl -s -G "$RAYTHA_URL/raytha/api/v1/ContentItems/posts" \
  -H "X-API-KEY: $RAYTHA_API_KEY" \
  --data-urlencode "filter=IsPublished eq 'true' and category eq 'news'" \
  --data-urlencode "orderBy=CreationTime desc" \
  --data-urlencode "pageNumber=1" \
  --data-urlencode "pageSize=10"

Always send the parameters URL-encoded. The filter contains spaces, quotes and parentheses. curl -G --data-urlencode, URLSearchParams in JavaScript and Uri.EscapeDataString in C# all do this for you.

Operators

Syntax	Meaning
`field eq 'x'`	Equal
`field ne 'x'`	Not equal. Includes items where the field is empty.
`field gt 5`, `ge`, `lt`, `le`	Greater than, greater or equal, less than, less or equal
`contains(field,'x')`	Contains the text, ignoring case
`startswith(field,'x')`	Starts with the text, ignoring case
`endswith(field,'x')`	Ends with the text, ignoring case
`field eq null`, `field ne null`	Has no value, has a value
`a and b`, `a or b`, `not a`	Combine conditions. Use parentheses to group.

That is the complete list. Raytha rejects in, arithmetic, string functions such as tolower, and the symbol =. Write eq.

Put text, dates and ids in single quotes. Numbers and booleans work with or without quotes. The CLI and the examples here quote booleans: IsPublished eq 'true'.
A single quote inside a value is doubled: title eq 'It''s here'.
The field is on the left. Comparing two fields, or a function result, is not supported.
eq on text is exact and case-sensitive. contains, startswith and endswith ignore case.

Which fields you can filter on

Use the field's developer name, spelled exactly as it is defined. Built-in fields use these names:

Field	Type	Example
`Id`	Item id	`Id eq 'h5anxM6u4UW80v09zzQjXg'`
`PrimaryField`	Stands for the type's primary field	`startswith(PrimaryField,'How')`
`CreationTime`, `LastModificationTime`	UTC timestamp	`CreationTime ge '2026-01-01T00:00:00Z'`
`IsPublished`, `IsDraft`	Boolean	`IsDraft eq 'false'`

You cannot filter on RoutePath, Template, CreatorUser or LastModifierUser. Raytha answers 400 with Field 'RoutePath' cannot be used in a filter. To look an item up by path, use the route endpoint.

Rules by field type

Field type	What you can write
Text (single line, long, rich text, color, attachment)	All operators. Compares the stored text.
Number	`eq ne gt ge lt le` with a decimal such as `3` or `3.5`. A non-number returns `Field 'rank' expects a numeric value.`
Date	Comparisons with `'2026-01-14'`. Only the date is compared. Your site's date format also works.
Checkbox	`eq` or `ne` with `'true'` or `'false'`
Dropdown, radio	Text operators against the choice's developer name
Multiple select	`tags eq 'launch'`, `ne` and `contains(tags,'launch')` all mean the item has that choice. `gt` and the other comparisons return `400`.
Relationship	`author eq '5qZGgMciiI-hQUnfKku_rk'` matches the related item by id. Any other value is compared with the related item's primary field text.
Repeater	Only `contains(items,'[]')`, which tests for an empty repeater

Combine these freely: (category eq 'news' or category eq 'guides') and rank ge 3 and summary ne null.

Dates and times

Send dates and timestamps as quoted ISO strings. An unquoted timestamp is converted using the server's culture and can change meaning.
CreationTime and LastModificationTime are UTC. A string without a zone is read as UTC.
A date field compares as a calendar date, so published_on le '2026-01-14' includes that day.

Sorting

orderBy is a comma-separated list of Field asc or Field desc:

orderBy=rank desc,CreationTime desc
orderBy=PrimaryField asc

You can sort by custom fields, PrimaryField, CreationTime and LastModificationTime. A relationship sorts by the related item's primary field.
Repeaters cannot be sorted. An unknown or unsortable field is skipped without an error, so check your spelling.
Without an orderBy, Raytha sorts newest first. Ties break on id, so paging is stable.
Sorting uses published content.

Search

search=launch returns items whose primary field contains the text, ignoring case. Add it to a filter to narrow further. With a viewId, the search covers the columns that view defines.

Paging

pageNumber starts at 1. pageSize defaults to 50 and is capped at 1000. A view can set its own maximum.
totalCount counts all matches. Stop when pageNumber * pageSize >= totalCount.
Changing the data while you page can shift items between pages. For an export, sort by CreationTime asc.

Views

viewId applies a saved view: its filter, its sort and its page size. Unless the view is set to ignore client parameters, your own filter is added to the view's filter with and, and your orderBy replaces the view's sort. Find view ids in the admin, or with GET /raytha/api/v1/contenttypes/{type}/views.

Errors

A bad filter returns 400 with the title Invalid filter and a message:

Message	Cause
`Unknown filter field 'x'.`	The name is not a field of this content type.
`Field 'x' cannot be used in a filter.`	A reserved field that is not filterable, or a relationship that cannot be resolved.
`Field 'x' cannot be used with this operator.`	For example `gt` on a repeater or multiple select.
`Field 'x' expects a numeric value.`, `… true or false.`, `… a date.`	The value does not match the field type.
`Unsupported function 'x'.`	Only contains, startswith and endswith exist.
`The filter expression could not be parsed: …`	Syntax error, such as a trailing `and` or an unclosed quote.

Gotchas

Filters read published content. A field saved only in a draft is invisible to the filter.
Build the value safely. If part of a filter comes from user input, double its single quotes before you insert it, or restrict it to a pattern such as [a-z0-9-]+.
Do not forget IsPublished eq 'true'. Lists include drafts and unpublished items.
The same syntax works in templates. OData in templates covers the Liquid side.

Next steps

Content items: the full list of endpoints.
Recipes: fetch every page, in JavaScript and C#.
Errors: the other failure shapes.