← Vibe Make
DOCS / DELIVERY API

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

認証

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 が使えます。

パラメータ範囲・既定説明
limit0〜100(既定10)一覧の1ページあたりの件数。
offset0以上(既定0)先頭から読み飛ばす件数。
ids1,000件までContent IDをカンマ区切りまたは繰り返し指定し、そのIDだけに限定する。
q1〜256文字全文検索。公開インデックスの検索テキストを対象に照合する。
filters複数指定可絞り込み条件。構文は「filtersの構文」を参照。複数指定時はAND条件になる。
orders最大100フィールド並び順。カンマ区切りで、先頭の`-`は降順。省略時は管理画面の表示順。
fields最大100項目返すフィールドを限定する。`parent.child`でネストを指定可能。idや日時も明示が必要。
depth0〜3(既定1)参照フィールドの展開深さ。0は`{"id": "..."}`のみを返す。
draftKey—指定したContentの保存済み下書きを返すプレビューキー。
richEditorFormathtml(既定)/ 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 で決まります。

  1. 通常キーのみ:公開済みのスナップショットを返します。
  2. 通常キー+draftKey:指定Contentの保存済み下書きを返します。一覧では、そのContentだけを公開一覧へ追加・差し替えてから、ids・検索・filters・orders・ページングを適用します。
  3. 下書き全取得キー:一覧・詳細とも、保存済みの現在値と未公開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、dprw・hは1以上。dprは0.01〜8。max-w/max-hにはfit=cropが必要。
配置・切り抜きfit、cropfit=clip/clamp/crop/fill/fillmax/max/min/scale。crop=center/top/bottom/left/rightとその組み合わせ、entropy、attention。
余白・背景fill=blur、fill-color、padfill-colorはRGB/RGBAの16進。fill=blurにはfit=fill/fillmaxとw/hが必要。
出力q、fm、dlqは0〜100(既定75)。fm=jpg/jpeg/png/webp/avif/gif/json。dlはファイル名を指定してダウンロード。
枠線・形状border、mask、corner-radiusmask=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-ytxt-fit=maxのみ。フォントは実行環境のものを使用。
画像合成mark、mark-alpha、mark-alignmarkには同じ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内の公開・更新・停止・アーカイブを発生順で返します。「配信イベントの読取」権限が必要です。

パラメータ範囲・既定説明
afterISO 8601日時この日時以降のイベントを返します。
afterIdイベントID同じ日時内の起点。after と併用が必要です。
limit1〜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クエリパラメータやフィールド指定が不正な場合
401APIキー未指定・無効・期限切れ、またはdraftKey/previewTokenが無効な場合
403APIキーが対象Projectまたは必要な権限を持たない場合
404公開中のContent、または公開Assetが見つからない場合
416Rangeがファイル範囲外の場合
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",
});

キャッシュとHTTPヘッダー