クエリ仕様

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

一覧表

limit=・offset=・depth=のような空文字は400になります。orders=は既定の並び順、fields=は全フィールド、q=・filters=は検索・絞り込みなしとして扱います。

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

ページング：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=-publishedAtorders=-priority,titleorders=-viewsorders=views

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

viewsは記事の累計閲覧数です。-viewsは多い順、viewsは少ない順で、未計測は0です。同数では公開日の新しい順になります。設定はPV(ページビュー)を参照してください。

絞り込み：filters

フィールドID[演算子]値の形式です。フィールドの表示名ではなくIDを使います。1,000文字の上限は、フィールドID・演算子・値・連結記号を含むfilters文字列全体に適用されます。

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

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

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

メタ情報のcreatedAt・updatedAt・publishedAtにequals／not_equalsは使えません。日時を絞る場合はgreater_than／less_thanを使います。

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

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

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

参照先APIが設定されていない、見つからない、またはAPIキーの対象外の場合は、参照値はIDのまま返ります。受け取る側ではオブジェクトかどうかも確認してください。

多言語のクエリ

lang=enは、ワークスペースに設定した英語版を指定します。対象APIの多言語設定もオンである必要があります。langを省略するかメイン言語を指定すると、既存の取得と同じ結果になります。サブ言語に公開版がない場合のメイン言語への切り替えは、lang_fallback=trueを明示したときだけです。lang_fallback=falseまたは省略時は切り替えません。

include=_langsは、各コンテンツに_langs.current（実際に返した言語）と_langs.available（公開中で取得できる言語）を追加します。availableではメイン言語が公開中なら先頭です。下書きや未作成の版は含めません。レスポンス例を参照してください。

lang=en&lang_fallback=true&include=_langs

サブ言語では、一覧のfilters・q・orders・totalCountを、その言語の値で評価します。フォールバックが有効なら、各原稿で選ばれた言語の値が対象です。参照展開では、参照先のAPIも多言語なら同じ言語とフォールバック設定を使います。参照先APIが多言語でない場合は、そのメイン言語の公開版を使います。参照先に公開中の版がない場合のnullや除外、APIキーの対象外ならIDのままという規則は通常の参照と同じです。

langを指定したリクエストでは、未知の言語、lang_fallbackのtrue・false以外の値、includeの未知のキーは400です。多言語でないAPIへのサブ言語指定も400です。エラーと制限を参照してください。

フィールド選択：fields

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

fields=title,publishedAt

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

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

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