配信API

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

認証

/v1以下のエンドポイントに、対象ワークスペースで発行した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は実行するシェルの環境変数へ設定済みであることを想定します。

エンドポイント一覧

workspaceはワークスペースID（スラッグ。管理画面の/w/{slug}と同じ値）、endpointはAPIのエンドポイント、entryIdは配信レスポンスのidです。IDは、何も指定しなければgenko.meが発行する12桁の英数字ですが、編集画面の 記事設定 → URL → スラッグ で変更でき、他サービスからの取り込みでは元のIDをそのまま引き継ぎます。実際に入る値は[A-Za-z0-9_-]の1〜64文字です。

機械で読めるOpenAPI 3.1の定義と、APIの参照先をまとめたカタログを認証なしで公開しています。URLとツールへの読み込み方法はOpenAPI・APIカタログを参照してください。

一覧取得

リスト形式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'

{  "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}

該当する記事がない場合も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です。コンテンツIDの形式だけを検証する処理はなく、形式にかかわらず、該当するコンテンツがなければ404になります。

オブジェクト形式の取得

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

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

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

公開条件とプレビュー

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

公開中の原稿に保存された未公開の変更は、通常の一覧・単一・オブジェクト取得には含まれません。draftKeyを指定したプレビューでは、保存済みの未公開の変更を返します。

下書きプレビューは単一取得・オブジェクト取得でX-Draft-Keyヘッダーを指定することを推奨します。draftKeyクエリも使えますが、両方ある場合はヘッダーが優先されます。通常のAPIキーも必要です。一覧で指定しても、下書き一覧にはなりません。プレビューURLは共有せず、公開後はキーを再生成してください。

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

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

クエリパラメータ

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

多言語の配信

多言語を有効にしたAPIではlangにワークスペースのサブ言語コードを指定します。省略、またはメイン言語を指定した場合は、従来のメイン言語の結果です。言語版の公開状態・公開期間は独立しています。メイン言語が下書きでも、公開中のサブ言語版だけを配信できます。

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

{  "id": "abcDEF123456",  "title": "First article",  "createdAt": "2026-09-01T00:00:00.000Z",  "updatedAt": "2026-09-01T01:00:00.000Z",  "publishedAt": "2026-09-01T01:00:00.000Z",  "_langs": { "current": "en", "available": ["ja", "en"] }}

一覧では/v1/your-workspace/blog?lang=en、オブジェクト形式では/v1/your-workspace/profile?lang=enを使います。サブ言語の公開版がない場合、一覧から除外され、単一・オブジェクト取得は404です。lang_fallback=trueを加えた場合だけ、公開中のメイン言語版を代わりに返します。一覧の検索・絞り込み・並び順・totalCountは、各行で実際に返す言語の値で計算します。

curl --get 'https://api.genko.me/v1/your-workspace/blog' \  -H "X-API-KEY: ${GENKO_API_KEY}" \  --data-urlencode 'lang=en' \  --data-urlencode 'lang_fallback=true' \  --data-urlencode 'include=_langs'

英語版が未公開で、メイン言語の日本語版が公開中の行は次の形で返ります。

{  "id": "abcDEF123456",  "title": "はじめての記事",  "createdAt": "2026-09-01T00:00:00.000Z",  "updatedAt": "2026-09-01T01:00:00.000Z",  "publishedAt": "2026-09-01T01:00:00.000Z",  "_langs": { "current": "ja", "available": ["ja"] }}

フォールバックした行の_langs.currentはメイン言語、availableは実際に公開中の言語の一覧です。include=_langsを指定しなければ_langsは付きません。下書きプレビューにはその言語版のdraftKeyをlangと一緒に指定し、プレビュー時はフォールバックしません。設定手順も参照してください。

スキーマ取得

_schemaは、CLIの型生成に必要なAPI定義を返します。APIキーの対象を限定している場合は、許可された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です。

記事の閲覧数を取得する

GET /v1/{workspace}/_views/{endpoint}はAPIキーが必要です。指定したAPIの記事について、累計と直近の日別集計の合計を返します。

curl --get 'https://api.genko.me/v1/your-workspace/_views/blog' \  -H "X-API-KEY: ${GENKO_API_KEY}" \  --data-urlencode 'ids=abcDEF123456,another-entry' \  --data-urlencode 'days=30'

{  "days": 30,  "views": {    "abcDEF123456": { "total": 120, "recent": 42 },    "another-entry": { "total": 0, "recent": 0 }  }}

totalは累計、recentは指定期間の合計です。そのAPIに属する記事ではないIDは両方0になります。記事の閲覧数はワークスペース内の公開IDで集計するため、異なるAPIに同じIDの記事がある場合は同じ閲覧数を共有します。SDKではgenko.apis.blog.views({ ids: ["abcDEF123456"], days: 30 })を使います。低レベルクライアントにはclient.getViews(...)があります。詳しくはSDKリファレンスを参照してください。

公開PVエンドポイント

以下の/pvエンドポイントはAPIキー不要です。ベースURLは配信APIと同じhttps://api.genko.meです。設定と部品の使い方はPV(ページビュー)を参照してください。

閲覧を送信する

POST /pv/{workspace}へ、JSON文字列をContent-Type: text/plainで送ります。

{ "path": "/blog/x", "entryId": "abcDEF123456" }

pathは必須、entryIdは任意です。entryIdなしならパスだけ、指定ありなら記事だけを加算します。パスと記事の両方を数える場合はそれぞれ送信してください。登録した受付ドメインのOriginだけを受け付け、localhost・ボット・重複・レート制限による除外も含め、常に204を返します。204は加算を保証しません。

累計を取得する

curl --get 'https://api.genko.me/pv/your-workspace/counts' \  --data-urlencode 'entryId=a' \  --data-urlencode 'entryId=b' \  --data-urlencode 'path=/x'

{ "entries": { "a": 12, "b": 0 }, "paths": { "/x": 24 } }

GET /pv/{workspace}/countsはentryIdとpathをそれぞれ最大50件受け付けます。複数値はカンマ区切りではなく、パラメータを繰り返して指定します。結果は要求した文字列をキーとする累計で、未計測や不正な形式の値は0です。各上限の超過は400、存在しないワークスペースは404です。

公開累計にはAccess-Control-Allow-Origin: *とCache-Control: public, max-age=60, s-maxage=300が付きます。表示には最大約5分の遅れがあります。

エラーと運用

認証に成功した/v1リクエストのレスポンスには、一覧・単一・オブジェクト・スキーマのすべてでCache-Control: private, no-storeが付きます。認証後に返る400や404にも適用されます。

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

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