配信API

認証、一覧・単一・オブジェクト取得、スキーマ取得のHTTPリファレンス。

配信APIは、genko.meのコンテンツをJSONで取得する読み取り用APIです。ベースURLはhttps://api.genko.meです。記事の書き込みは管理画面から行います。

認証

すべてのエンドポイントに、対象ワークスペースで発行したAPIキーをX-API-KEYヘッダーで渡します。キーの発行手順はAPIキーの管理を参照してください。

curl 'https://api.genko.me/v1/your-workspace/blog' \
  -H "X-API-KEY: ${GENKO_API_KEY}"

以降のyour-workspace、blog、コンテンツIDは、自分の環境の値に置き換えます。GENKO_API_KEYは実行するシェルの環境変数へ設定済みであることを想定します。

エンドポイント一覧

メソッド	パス	対象
`GET`	`/v1/{workspace}/{endpoint}`	リスト形式の一覧、またはオブジェクト形式の1件
`GET`	`/v1/{workspace}/{endpoint}/{entryId}`	リスト形式の1件
`GET`	`/v1/{workspace}/_schema`	ワークスペース内のAPI定義

workspaceはワークスペースID、endpointはAPIのエンドポイント、entryIdは配信レスポンスのidです。IDは12文字の英数字で、タイトルや任意のURLスラッグではありません。

一覧取得

リスト形式APIのエンドポイントへリクエストします。

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

200のレスポンス例

{
  "contents": [
    {
      "id": "abcDEF123456",
      "title": "はじめての記事",
      "body": "<p>genko.meから届ける原稿です。</p>",
      "createdAt": "2026-09-01T00:00:00.000Z",
      "updatedAt": "2026-09-01T01:00:00.000Z",
      "publishedAt": "2026-09-01T01:00:00.000Z"
    }
  ],
  "totalCount": 1,
  "offset": 0,
  "limit": 10
}

キー	意味
`contents`	今回取得したコンテンツの配列
`totalCount`	公開条件と検索・絞り込み条件を満たす全件数
`offset`	取得開始位置
`limit`	1リクエストの取得上限

該当する記事がない場合も200で、contentsは空配列になります。管理画面の下書きを含む総件数とは一致しないことがあります。

単一コンテンツ取得

一覧で得たidをURLの末尾に指定します。

curl 'https://api.genko.me/v1/your-workspace/blog/abcDEF123456' \
  -H "X-API-KEY: ${GENKO_API_KEY}"

レスポンスは1件のオブジェクトです。contentsで包みません。

{
  "id": "abcDEF123456",
  "title": "はじめての記事",
  "body": "<p>genko.meから届ける原稿です。</p>",
  "createdAt": "2026-09-01T00:00:00.000Z",
  "updatedAt": "2026-09-01T01:00:00.000Z",
  "publishedAt": "2026-09-01T01:00:00.000Z"
}

存在しない、削除済み、または公開条件を満たさない場合は404です。

オブジェクト形式の取得

profileなどのオブジェクト形式では、IDを付けずに取得します。レスポンスは単一コンテンツと同じくオブジェクトを直接返します。

curl 'https://api.genko.me/v1/your-workspace/profile' \
  -H "X-API-KEY: ${GENKO_API_KEY}"

まだ保存されていない場合や、公開されていない場合は404です。オブジェクト形式に/{entryId}を付けた取得はできません。

公開条件とプレビュー

通常の取得では、「公開」、または公開開始日時を迎えた「公開予定」が対象です。公開終了日時を過ぎた記事は対象外です。配信APIはリクエスト時の日時も確認します。

下書きプレビューは単一取得・オブジェクト取得でdraftKeyを指定します。通常のAPIキーも必要です。一覧でdraftKeyを指定しても、下書き一覧にはなりません。

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

プレビューキーは1〜64文字です。不正な形式は400、正しい形式でも一致するコンテンツがなければ404になります。下書きプレビューで設定手順を確認できます。

クエリパラメータ

対象	パラメータ
一覧	`limit`、`offset`、`orders`、`filters`、`q`、`depth`、`fields`
単一・オブジェクト	`depth`、`fields`、`draftKey`

既定値・演算子・上限はクエリ仕様、フィールドごとの値はレスポンスの値にまとめています。

スキーマ取得

_schemaは、CLIの型生成に必要なAPI定義を返します。コンテンツの本文は返しません。

curl 'https://api.genko.me/v1/your-workspace/_schema' \
  -H "X-API-KEY: ${GENKO_API_KEY}"

{
  "workspace": "your-workspace",
  "apis": [
    {
      "name": "ブログ",
      "endpoint": "blog",
      "kind": "list",
      "fields": [
        { "id": "title", "name": "タイトル", "type": "text", "required": true }
      ]
    }
  ]
}

kindはlistまたはobjectです。このエンドポイントのレスポンスにはCache-Control: private, no-storeが設定されます。

エラーと運用

失敗時は{ "message": "..." }形式のJSONを返します。認証・レート制限・クエリの不正を区別して処理してください。エラーと制限にステータス別の対処を掲載しています。

APIはアプリ側のキャッシュを自動で更新しません。更新の反映にはWebhookやアプリ側の再取得方針を組み合わせます。

配信API

目次