Query reference

This page covers the query behavior that the delivery API and the SDK share. Over HTTP you set it in the URL's query string, and in the SDK you set it as method options. For examples of building queries in the SDK, see SDK queries.

Summary

An empty value such as limit=, offset=, or depth= returns 400. orders= is treated as the default sort order, fields= as all fields, and q= or filters= as no search or filter.

If you pass a parameter to a request type that doesn't support it, the feature isn't available. For example, you can't add a search condition to a single-entry request to restrict what it fetches.

Paging: limit / offset

offset is the starting position, counted from entry 0. With 10 entries per page, page 2 is offset=10 and page 3 is offset=20.

curl --get 'https://api.genko.me/v1/your-workspace/blog' \  -H "X-API-KEY: ${GENKO_API_KEY}" \  --data-urlencode 'limit=10' \  --data-urlencode 'offset=10'

If offset is past the total count, you get an empty array. If something is published or deleted partway through several requests, positions in the list shift, so you can get duplicates or miss entries. Don't treat a bulk fetch as a point-in-time backup.

Sorting: orders

Separate keys with commas, highest priority first. A leading - means descending, and no prefix means ascending.

orders=-publishedAtorders=-priority,titleorders=-viewsorders=views

You can use createdAt, updatedAt, publishedAt, views, or the field ID of a number, datetime, text, or boolean field. NULL values go last. If you keep an event date separate from the delivery date, name that date field explicitly.

views is the all-time entry view count. -views sorts most viewed first; views sorts least viewed first. Missing counts are zero. Ties are sorted by newest publication date. See Page views to set up counting.

Filtering: filters

The format is fieldID[operator]value. Use the field ID, not its display name. The 1,000-character limit applies to the whole filters string, including field IDs, operators, values, and the joining tokens.

category[equals]techfeatured[equals]true[and]priority[greater_than]3category[equals]news[or]category[equals]tech

The examples above need category (single select), featured (boolean), and priority (number) to be defined.

publishedAt[greater_than]2026-09-01T00:00:00.000Zeyecatch[exists]

You can't use equals / not_equals on the meta fields createdAt, updatedAt, and publishedAt. To filter by date, use greater_than / less_than.

exists checks whether a value is stored. It doesn't guarantee that a reference target is published or that an image can be fetched.

Join conditions with [and] or [or]. You can't mix both in one expression or group with parentheses. Check whether this syntax can express a complex condition, including any reserved tokens inside values.

Encoding over HTTP

Values that contain non-ASCII characters, spaces, or square brackets need URL encoding. Use curl --data-urlencode or URLSearchParams rather than joining them into the URL by hand.

curl --get 'https://api.genko.me/v1/your-workspace/blog' \  -H "X-API-KEY: ${GENKO_API_KEY}" \  --data-urlencode 'filters=category[equals]tech[and]featured[equals]true'

Text search: q

This searches text, textarea, and richtext fields with a case-insensitive partial match. An entry is a candidate if any of those fields match. It isn't morphological analysis or relevance-ranked search.

q=new feature

If you also pass filters, results are narrowed to entries that meet those conditions too. It can't search dates or the contents of images.

Reference expansion: depth

For example, an entry that references author looks like "author": "authorID1234" with depth=0, and "author": { "id": "authorID1234", "name": "Author name", ... } with depth=1.

When references are expanded, a referenced entry that doesn't meet the publishing conditions becomes null for a single reference and is dropped from the array for multiple references. Even during preview, referenced entries show only their published content.

If the referenced API isn't set, can't be found, or isn't allowed by the API key, the reference value comes back as the ID. On the receiving side, check whether the value is an object.

Multilingual queries

lang=en selects the English version set up in the workspace. The target API must also have multilingual support turned on. If you omit lang or pass the main language, you get the same result as an ordinary fetch. Falling back to the main language when an additional language has no published version happens only when you set lang_fallback=true explicitly. With lang_fallback=false or when omitted, it doesn't fall back.

include=_langs adds _langs.current (the language actually returned) and _langs.available (the live languages you can fetch) to each entry. In available, the main language comes first if it's live. Drafts and versions that haven't been created aren't included. See the example response.

lang=en&lang_fallback=true&include=_langs

For an additional language, a list's filters, q, orders, and totalCount are evaluated with that language's values. With fallback on, the values of the language chosen for each entry are used. For reference expansion, if the referenced API is also multilingual, the same language and fallback settings apply. If it isn't multilingual, its live main-language version is used. The rules for null or exclusion when the referenced entry has no live version, and for returning the ID when the API key doesn't allow it, are the same as for ordinary references.

In a request with lang, an unknown language, a lang_fallback value other than true or false, or an unknown include key returns 400. Passing an additional language to an API that isn't multilingual also returns 400. See Errors and limits.

Field selection: fields

Name the fields to return as a comma-separated list of field IDs. In the SDK you can also pass an array of strings.

fields=title,publishedAt

{  "title": "My first post",  "id": "abcDEF123456",  "publishedAt": "2026-09-01T01:00:00.000Z"}

• id is always included.
• createdAt, updatedAt, and publishedAt are returned only if you include them in fields.
• Unknown IDs are ignored. A typo doesn't cause an error, so be careful.
• Fields on expanded references aren't narrowed.
• The SDK's return type isn't narrowed to match fields automatically. Don't read values you didn't request.

For responses to invalid queries, see Errors and limits.