Search and filter

list() and getAll() support search, filters, and sorting. getAll() handles pagination internally, so it does not accept limit or offset.

The examples below assume that category (single select), featured (boolean value), priority (number), and author (reference) are added to blog. After changing the schema, synchronize the types with pull.

Paging and sorting

import { genko } from "@/lib/client";
const page = 2;const pageSize = 10;const result = await genko.apis.blog.list({  limit: pageSize,  offset: (page - 1) * pageSize,  orders: "-publishedAt",});
const hasNext = result.offset + result.contents.length < result.totalCount;

orders: "-priority,title" sorts by priority descending, then by title ascending for equal priorities. You can check the field types and maximum number of keys that can be used in Query specifications.

Use orders: "-views" for most viewed first, or orders: "views" for least viewed first. These use all-time entry counts, with missing counts treated as zero. Set up counting with Page views.

const popular = await genko.apis.blog.list({ orders: "-views", limit: 4 });

Filter by field

import { buildFilters } from "@genko-me/sdk";import { genko } from "@/lib/client";
const filters = buildFilters()  .equals("featured", true)  .and()  .greaterThan("priority", 3);
const result = await genko.apis.blog.list({ filters });

The same condition applies if you pass the string "featured[equals]true[and]priority[greater_than]3". The builder assembles the string; it does not verify field IDs against the schema.

You can pass strings, numbers, boolean values, and Date as values. Date is converted to ISO 8601. exists and notExists take no values.

Mixing and and or in the same expression will result in an exception. If the operator and type do not match, the delivery API will return 400.

Combine with text search

const result = await genko.apis.blog.list({  q: "new features",  filters: "category[equals]news",  orders: "-publishedAt",});

Fetches posts whose text contains "new features" and whose category is news. q is not a ranking based on relevance or a search for characters in images.

Specify reference expansion

const post = await genko.apis.blog.getOrNull("abcDEF123456", { depth: 1 });const author = post?.author;
if (author && typeof author === "object" && "name" in author) {  if (typeof author.name === "string") console.log(author.name);}

The generated type of reference is unknown, so in the above example, we check the shape and use it. depth: 0 returns the ID; depth: 1 expands one level, and depth: 2 expands two levels. Also consider unpublished references and missing references. Even if the referenced API is not covered by the key, it remains an ID and is not expanded.

Get only the necessary items

const { contents } = await genko.apis.blog.list({  fields: ["title", "publishedAt"],  depth: 0,});
for (const post of contents) {  console.log(post.id, post.title);}

id is always returned. Fields you omit are not included in the response. The TypeScript type of the return value is not automatically reduced, so even if the type check passes, it doesn't necessarily mean that post.body actually exists.

For default values and limits of all parameters common to HTTP and SDK, please refer to Query specifications.

Specify and get the language

For APIs with multiple languages, pass the additional language code in lang. If omitted, the result is the main language. The following example fetches only entries with a published English version.

import { genko } from "@/lib/client";
const { contents, totalCount } = await genko.apis.blog.list({  lang: "en",  include: ["_langs"],});const article = await genko.apis.blog.getOrNull("abcDEF123456", {  lang: "en",  include: ["_langs"],});const allEnglish = await genko.apis.blog.getAll({ lang: "en" });
for (const post of contents) {  console.log(post.id, post._langs?.current, post._langs?.available);}

getAll() uses the same language specification to retrieve each page. In object format, use genko.apis.profile.get({ lang: "en" }). Add langFallback: true to fall back to the published main language when the requested language has no published version. Fallback is off by default. _langs.current is the language actually returned, and _langs.available is the list of languages ​​currently available.

Search, filtering, sorting, and total number of results for a list that specifies a language are calculated based on the language value actually returned. Please refer to Query specifications for URL parameters and error conditions.