クエリ仕様

ページング、絞り込み、検索、並び替え、参照展開、フィールド選択の制約と例。

このページは、配信APIとSDKに共通するクエリの仕様です。HTTPではURLのクエリ、SDKではメソッドのオプションとして指定します。SDKでの組み立て例はSDKのクエリを参照してください。

一覧表

パラメータ	対象	既定値	制約
`limit`	一覧	`10`	1〜100の整数
`offset`	一覧	`0`	0以上の整数
`orders`	一覧	`-publishedAt`	最大3キー
`filters`	一覧	なし	最大10条件・1,000文字
`q`	一覧	なし	最大100文字
`depth`	一覧・単一・オブジェクト	`1`	`0`、`1`、`2`
`fields`	一覧・単一・オブジェクト	全フィールド	最大50項目

対応しない種類のパラメータを渡しても、その機能は利用できません。たとえば単一取得に検索条件を付けて、取得を制限する用途には使えません。

ページング：limit / offset

offsetは0件目から数えた開始位置です。1ページ10件なら、2ページ目はoffset=10、3ページ目は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'

offsetが件数を超えた場合は空配列になります。複数リクエストの途中に公開・削除が起きると一覧の位置が変わり、重複や取りこぼしが起きる可能性があります。一括取得を、時点を固定したバックアップとして扱わないでください。

並び替え：orders

カンマ区切りで優先順位の高いキーから指定します。先頭に-を付けると降順、付けなければ昇順です。

orders=-publishedAt
orders=-priority,title

指定できるのは、createdAt・updatedAt・publishedAt、またはnumber・datetime・text・booleanのフィールドIDです。NULLは末尾に配置されます。配信日時と別にイベント日時を持っている場合は、その日時フィールドを明示してください。

絞り込み：filters

フィールドID[演算子]値の形式です。フィールドの表示名ではなくIDを使います。

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

上の例には、それぞれcategory（単一セレクト）、featured（真偽値）、priority（数字）が定義されている必要があります。

演算子	対象の種類	値
`equals` / `not_equals`	text、textarea、単一select、boolean、number、reference、メタの`id`	完全一致。真偽値は`true`／`false`
`contains` / `not_contains`	text、textarea、richtext	大文字小文字を区別しない部分一致
`contains` / `not_contains`	複数select、references	配列の要素との完全一致
`greater_than` / `less_than`	number、datetime、メタの日時	数値またはISO 8601の日時。境界値は含まない
`exists` / `not_exists`	すべてのフィールド種別	値を付けない

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

existsは保存されている値の有無の判定です。参照先が公開されていることや、画像が取得できることを保証する条件ではありません。

条件は[and]または[or]でつなぎます。1つの式で両方を混ぜたり、括弧でグループ化したりすることはできません。値の中の予約記号も含め、複雑な条件はこの構文で表現可能か確認してください。

HTTPでのエンコード

日本語、空白、角括弧などを含む値はURLエンコードが必要です。手動でURLへ連結するより、curl --data-urlencodeやURLSearchParamsを使ってください。

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'

テキスト検索：q

text・textarea・richtextの各フィールドを、大文字小文字を区別しない部分一致で検索します。いずれかの対象フィールドが一致すれば候補になります。形態素解析や関連度順の検索ではありません。

q=新機能

filtersも指定した場合は、その条件も満たすコンテンツに絞られます。日時や画像の内容を検索する機能ではありません。

参照展開：depth

値	レスポンス
`0`	参照先のIDを返す
`1`	参照先の内容を1階層展開する。既定値
`2`	参照先が持つ参照も、もう1階層展開する

たとえばauthorを参照する記事は、depth=0なら"author": "authorID1234"、depth=1なら"author": { "id": "authorID1234", "name": "著者名", ... }という形になります。

公開条件を満たさない参照先は、単一参照ではnull、複数参照では配列から除外されます。プレビュー中も参照先は公開された内容だけです。

参照先APIが設定されていない、または参照先APIを解決できない場合は、IDのまま返ることがあります。受け取る側ではオブジェクトかどうかも確認してください。

フィールド選択：fields

返す項目をフィールドIDのカンマ区切りで指定します。SDKでは文字列配列も使えます。

fields=title,publishedAt

単一コンテンツのレスポンス例

{
  "title": "はじめての記事",
  "id": "abcDEF123456",
  "publishedAt": "2026-09-01T01:00:00.000Z"
}

idは常に含まれます。
createdAt・updatedAt・publishedAtは、fieldsに含めた場合だけ返ります。
存在しないIDは無視されます。誤字でもエラーにならないため注意してください。
展開された参照先の項目は絞り込まれません。
SDKの戻り値型はfieldsに合わせて自動では絞り込まれません。指定しなかった値を参照しないでください。

不正なクエリへの応答はエラーと制限を参照してください。

クエリ仕様

目次