CMS API リファレンス
Vibe MakeのヘッドレスCMS配信APIは、公開中のContentをJSONで取得する読み取り専用のWeb APIです。 クエリとレスポンス形式はmicroCMSのコンテンツAPIと互換性があり、既存サイトからの移行では取得メソッドと値の読み取り方をそのまま維持できます。
概要
配信APIはVibe MakeのWebアプリのオリジン(本番は https://vibemk.ai)で提供されます。 メソッドはGETのみで、すべてのJSONレスポンスはUTF-8です。Projectで「単一オブジェクト形式」を設定している場合、 一覧エンドポイントはラッパーなしの単一オブジェクトを直接返します。
パスに使う workspaceSlug はWorkspaceのスラッグ、endpoint はProjectに設定したendpointキーです。 実際の配信URLはアプリの「ヘッドレスCMS」画面の配信URL一覧と、Workspace設定の「Webサイトの接続情報」で確認できます。
microCMSとの互換性は、本ページに記載する読み取りAPIのクエリ・入出力形式が対象であり、完全互換ではありません。 全文検索の結果・順位、リッチエディタ由来のHTML出力、画像バイナリや未対応の変換指定には差分があります。 既存サイトの切り替えでは、代表ページのJSON・HTML・画像・未公開プレビューを比較検証してから実施してください。
エンドポイント
GET/api/v1/delivery/{workspaceSlug}
CMS APIキーが取得できるProject一覧と権限を返します。詳しくは「Project一覧」を参照してください。
GET/api/v1/delivery/{workspaceSlug}/{endpoint}
公開中のContent一覧を返します。単一オブジェクト形式のProjectではそのオブジェクトを返します。
GET/api/v1/delivery/{workspaceSlug}/{endpoint}/{contentId}
指定したContent IDの詳細を返します。
GET/api/v1/delivery/{workspaceSlug}/{endpoint}/{contentId}/assets/{assetId}
Contentに含まれる画像・ファイルのバイナリを返します。クエリで画像変換を指定できます。
GET/api/v1/delivery-events/{workspaceSlug}/{endpoint}
公開・更新・停止・アーカイブの配信イベントを返します。
Project一覧
GET /api/v1/delivery/{workspaceSlug} は、CMS APIキーで取得可能なProjectの一覧を返します。 認証はContent APIと同じ X-MICROCMS-API-KEY ヘッダーを使いますが、projectKeyは要求せず、 Workspaceに属するキーとして有効性・環境・失効状態・有効期限を検証します。 未指定・無効・失効・期限切れ、または別環境のキーは401を返します。
{
"projects": [
{
"name": "記事",
"projectKey": "articles",
"endpoint": "https://vibemk.ai/api/v1/delivery/my-workspace/articles",
"mode": "collection"
}
],
"permissions": ["publishedContent:read", "deliveryEvents:read"]
}nameはProjectの表示名、projectKeyはendpointキー、endpointはContent APIのベースURL、modeはcollection(一覧形式)またはsingle(単一オブジェクト形式)です。permissionsはキーに付与された権限で、publishedContent:read・draftContent:read・deliveryEvents:readのうち有効なものを返します。- キーの対象に含まれないProject(新規作成したProjectを含む)と、アーカイブ済みのProjectは返されません。キーの対象から外したProjectは、次回のレスポンスとContent API・配信イベントAPIへのアクセスの両方から除外されます。
- 内部のProject IDやAPIキーのハッシュなどの内部情報は返しません。
認証
Content APIと配信イベントAPIは、リクエストヘッダー X-MICROCMS-API-KEY にCMS APIキーを指定して認証します。 キーはWorkspace設定の「CMS APIキー」で発行し、対象のProjectsと権限、有効期限を選択します。
curl "https://vibemk.ai/api/v1/delivery/my-workspace/articles?limit=10" \
-H "X-MICROCMS-API-KEY: vmcms_prod_…"| 権限 | 内容 |
|---|---|
| 公開Contentの読取 | 一覧・詳細APIで公開済みのContentを取得します。 |
| 下書き全取得(プレビューサイト用) | 一覧・詳細とも、保存済みの現在値と未公開Contentを返します。公開サイト用キーとは分けてください。 |
| 配信イベントの読取 | 配信イベントAPIを利用できます。 |
APIキーはサイトのサーバー環境変数に保存し、フロントエンドの公開環境変数やブラウザへ露出させないでください。
公開Asset(画像・ファイル)の取得にAPIキーは不要です。下書きのAssetはdraftKeyまたは期限付きの署名トークンが必要です。
クエリパラメータ
一覧APIで利用できるクエリです。詳細APIでは depth・fields・draftKey・richEditorFormat が使えます。
| パラメータ | 範囲・既定 | 説明 |
|---|---|---|
limit | 0〜100(既定10) | 一覧の1ページあたりの件数。 |
offset | 0以上(既定0) | 先頭から読み飛ばす件数。 |
ids | 1,000件まで | Content IDをカンマ区切りまたは繰り返し指定し、そのIDだけに限定する。 |
q | 1〜256文字 | 全文検索。公開インデックスの検索テキストを対象に照合する。 |
filters | 複数指定可 | 絞り込み条件。構文は「filtersの構文」を参照。複数指定時はAND条件になる。 |
orders | 最大100フィールド | 並び順。カンマ区切りで、先頭の`-`は降順。省略時は管理画面の表示順。 |
fields | 最大100項目 | 返すフィールドを限定する。`parent.child`でネストを指定可能。idや日時も明示が必要。 |
depth | 0〜3(既定1) | 参照フィールドの展開深さ。0は`{"id": "..."}`のみを返す。 |
draftKey | — | 指定したContentの保存済み下書きを返すプレビューキー。 |
richEditorFormat | html(既定)/ object | リッチエディタ本文の形式。objectは旧リッチエディタ由来の本文をブロック構造で返す。 |
例
GET /api/v1/delivery/my-workspace/articles
?limit=20
&orders=-publishedAt
&filters=category[equals]news[and]title[contains]AI
&fields=id,title,category未定義のクエリ名(綴り違いを含む)は無視されます。draftKey を除く上表のパラメータに未対応・範囲外の値を指定した場合や、 filters・ordersの構文が不正な場合のみ400エラーになります。無効・失効済み・対象外のdraftKeyは401エラーになります。format パラメータは廃止されており、指定すると400エラーになります。
filtersの構文
field[operator]value の条件を、[and]・[or]・括弧で連結します。 フィールド名はドット区切りでネストを表せます(例 author.name)。
| 演算子 | 条件 |
|---|---|
equals | 値が一致する |
not_equals | 値が一致しない |
contains | 値を含む(部分一致。選択肢・参照フィールドは値単位の完全一致) |
not_contains | 値を含まない |
begins_with | 値で始まる(前方一致) |
less_than | 値より小さい(数値・日時・文字列) |
greater_than | 値より大きい(数値・日時・文字列) |
exists | 値が存在する(値は指定しない) |
not_exists | 値が存在しない(値は指定しない) |
# カテゴリがnewsで、タイトルにAIまたはagentを含む
filters=category[equals]news[and](title[contains]AI[or]title[contains]agent)URLのクエリへ埋め込む際は [ ] ( ) などをURLエンコードしてください。
レスポンス形式
一覧APIは次の形式を返します。
{
"contents": [
{
"id": "release-2026-09",
"createdAt": "2026-09-01T02:00:00.000Z",
"updatedAt": "2026-09-10T09:30:00.000Z",
"publishedAt": "2026-09-10T09:45:00.000Z",
"revisedAt": "2026-09-10T09:45:00.000Z",
"title": "…",
"category": { "id": "news" }
}
],
"totalCount": 42,
"offset": 0,
"limit": 10
}publishedAt・revisedAt は存在する場合のみ返ります。詳細APIはid・createdAt・updatedAt・publishedAt・revisedAt に スキーマの各フィールドを加えた単一オブジェクトを返します。フィールド型ごとの出力は次のとおりです。
| フィールド型 | 出力 | 例 |
|---|---|---|
| テキスト・数値・真偽値・日時 | そのままの値 | "東京" / 120 / true / "2026-09-01T00:00:00.000Z" |
| 選択肢 | ラベルの配列 | ["ニュース", "重要"] |
| 画像 | {url, width, height, alt} | {"url": ".../assets/...", "width": 800, "height": 450} |
| ファイル | {url, fileSize} | {"url": ".../assets/...", "fileSize": 102400} |
| 参照 | depth=0では{"id": "..."}、depth指定で参照先オブジェクトを展開 | {"id": "category-1", "title": "..."} |
| カスタムフィールド | {fieldId, ...子フィールド} | {"fieldId": "profile", "name": "..."} |
| 繰り返し | 上記のいずれかの配列 | [{...}, {...}] |
| リッチエディタ | HTML文字列。richEditorFormat=objectでブロック構造 | "<h2>...</h2><p>...</p>" |
参照フィールドは、参照先のProjectへのアクセスをAPIキーで認可して展開します。非公開・権限外の参照は結果から除外されます。
fields を指定した場合は、指定したキーのみが返ります(idや日時が必要な場合は明示してください)。
下書きとプレビュー
下書きの取得方法はAPIキーの権限と draftKey で決まります。
- 通常キーのみ:公開済みのスナップショットを返します。
- 通常キー+
draftKey:指定Contentの保存済み下書きを返します。一覧では、そのContentだけを公開一覧へ追加・差し替えてから、ids・検索・filters・orders・ページングを適用します。 - 下書き全取得キー:一覧・詳細とも、保存済みの現在値と未公開Contentを返します。プレビューサイト専用に分けてください。
「サイトでプレビュー」が発行するdraftKeyは15分で失効し、Contentごとに1枠です。再度プレビューすると以前のリンクは失効します。 手動で発行したdraftKeyは下書き管理画面から失効できます。未公開Contentに架空の publishedAt・revisedAt は付きません。
下書きのJSONと画像は Cache-Control: private, no-store で返ります。プレビューURLやその画像URLを永続キャッシュに保存しないでください。
Assetと画像変換
レスポンス内の画像・ファイルURLは /api/v1/delivery/…/{contentId}/assets/{assetId} を指します。 公開Assetは認証なしで取得でき、Rangeリクエスト(206/416)とETagによる304に対応します。
画像には次の変換クエリを指定できます。対応表にないパラメータ・値はエラーになります。
| 用途 | パラメータ | 備考 |
|---|---|---|
| サイズ | w、h、max-w、max-h、dpr | w・hは1以上。dprは0.01〜8。max-w/max-hにはfit=cropが必要。 |
| 配置・切り抜き | fit、crop | fit=clip/clamp/crop/fill/fillmax/max/min/scale。crop=center/top/bottom/left/rightとその組み合わせ、entropy、attention。 |
| 余白・背景 | fill=blur、fill-color、pad | fill-colorはRGB/RGBAの16進。fill=blurにはfit=fill/fillmaxとw/hが必要。 |
| 出力 | q、fm、dl | qは0〜100(既定75)。fm=jpg/jpeg/png/webp/avif/gif/json。dlはファイル名を指定してダウンロード。 |
| 枠線・形状 | border、mask、corner-radius | mask=ellipse/corners。corner-radiusの既定は10。 |
| テキスト | txt、txt-align、txt-clip、txt-color、txt-fit、txt-font、txt-size、txt-line、txt-line-color、txt-pad、txt-shad、txt-width、txt-x、txt-y | txt-fit=maxのみ。フォントは実行環境のものを使用。 |
| 画像合成 | mark、mark-alpha、mark-align | markには同じWorkspaceへ取り込んだ画像の配信URLを指定。mark-alphaは0〜100。 |
/api/v1/delivery/my-workspace/articles/release-2026-09/assets/hero?w=800&fm=webp&q=80配信イベント
GET /api/v1/delivery-events/{workspaceSlug}/{endpoint} は、 Project内の公開・更新・停止・アーカイブを発生順で返します。「配信イベントの読取」権限が必要です。
| パラメータ | 範囲・既定 | 説明 |
|---|---|---|
after | ISO 8601日時 | この日時以降のイベントを返します。 |
afterId | イベントID | 同じ日時内の起点。after と併用が必要です。 |
limit | 1〜500(既定100) | 返す件数の上限。 |
{
"items": [
{
"id": "…",
"type": "content.published",
"projectId": "…",
"projectKey": "articles",
"contentId": "release-2026-09",
"contentVersion": 3,
"artifactSha256": "…",
"publishedAt": "2026-09-10T09:45:00.000Z",
"createdAt": "2026-09-10T09:45:01.000Z"
}
]
}type は content.published・content.updated・content.unpublished・content.archived のいずれかです。
エラーレスポンス
エラーはHTTPステータスと、トップレベルの message を持つJSONを返します。
{ "message": "公開中のデータが見つかりません。" }| ステータス | 意味 |
|---|---|
400 | クエリパラメータやフィールド指定が不正な場合 |
401 | APIキー未指定・無効・期限切れ、またはdraftKey/previewTokenが無効な場合 |
403 | APIキーが対象Projectまたは必要な権限を持たない場合 |
404 | 公開中のContent、または公開Assetが見つからない場合 |
416 | Rangeがファイル範囲外の場合 |
500 | サーバー内部のエラー |
SDK
TypeScript向けに読み取り専用クライアント @vibe-make/cms-client を用意しています。get・getList・getListDetail・getObject・getAllContents・getAllContentIds は microcms-js-sdkの読み取り呼び出しと同じ形で使えます。
import { createClient } from "@vibe-make/cms-client";
const client = createClient({
baseUrl: process.env.CMS_BASE_URL!, // Workspace設定の共通ベースURL
apiKey: process.env.CMS_API_KEY!, // サーバーのみが保持するCMS APIキー
});
const articles = await client.getList<Article>({ endpoint: "articles" });
const article = await client.getListDetail<Article>({
endpoint: "articles",
contentId: "release-2026-09",
});preview: trueを指定すると全下書き用の接続になり、すべてのfetchキャッシュをバイパスします。draftKeyを含む呼び出しも自動でcache: "no-store"になります。retry: trueで429・5xx・通信エラーを指数バックオフで再試行します。- パッケージはリポジトリから配布用に生成します(npm registryへの公開は含みません)。
キャッシュとHTTPヘッダー
- 正常なJSONレスポンスとAssetには
ETagが付きます。同じETagをIf-None-Matchで送ると変更がない場合に304を返します(エラーレスポンスには付きません)。 - 公開ContentのJSONは
Cache-Control: private, max-age=0, must-revalidate、公開Assetはpublic, no-cache, max-age=0, s-maxage=0, must-revalidate、下書きはprivate, no-storeです。 - 公開Assetは同じURLへの次のHTTPリクエストでも現在の公開状態を再検証します。許可が続き画像が同じなら304で本文転送を省略し、公開停止・Archive・削除後は保存済み画像を再検証なしで返しません。プレビュー画像は
private, no-storeです。変更前のheaderで保存済みのcacheには旧TTLが残り得ます。配信済みの画像bytesは回収できません。 - CORSは
Access-Control-Allow-Origin: *、許可メソッドはGET, OPTIONSです。 - Assetは
Accept-Ranges: bytesと単一範囲のRangeに対応し、Content-Dispositionで元のファイル名を返します。