管理API
管理APIを使うと、サイト・リソース・データ・素材の作成や更新、公開を、プログラムやスクリプトから行えます。個人用のAPIトークンで認証し、自分が所有するサイトだけを操作できます。静的サイトから公開データを読むだけなら、管理APIではなく 公開API を使ってください。
APIトークン
発行する
- 管理画面の上部メニューから「アカウント・API」を開きます。
- 「管理APIトークン」の「名前」に用途（例：開発用クライアント）を入力し、「トークンを発行」を押します。
- 表示されたトークンをコピーします。トークンはこの画面で一度だけ表示されます。
| 項目 | 内容 |
|---|---|
| 有効期間 | 発行から90日。期限は一覧に「YYYY/MM/DD まで」と表示されます。 |
| 権限 | 発行したユーザーが所有するすべてのサイトへの管理権限 |
| 失効 | 一覧の「失効」を押すと、すぐに使えなくなります。 |
期限が切れたら、新しいトークンを発行してください。トークンは管理権限を持つため、公開サイトのHTMLやJavaScriptには絶対に埋め込まないでください。
送り方
Authorization ヘッダーに Bearer 形式で付けます。
Authorization: Bearer YOUR_TOKEN
トークンがない、誤っている、または期限切れの場合は 401 になります。
エンドポイント一覧
ベースURLは https://cms.magichtml.dev/api/v1 です。{site}・{resource}・{entry}・{asset} には、それぞれのID（UUID）を指定します。
サイト
| メソッド | パス | 内容 |
|---|---|---|
GET |
/sites |
自分のサイトの一覧（リソース数つき） |
POST |
/sites |
サイトを作成（name：100文字まで） |
GET |
/sites/{site} |
サイトの詳細（リソースと素材の一覧を含む） |
PUT |
/sites/{site} |
サイト名と接続元を更新（name、origins） |
DELETE |
/sites/{site} |
サイトを削除（リソース・公開履歴・素材もすべて削除） |
PUT /sites/{site} の origins は、接続元の配列（または改行区切りの文字列）で、指定した内容で一覧全体が置き換わります。origins を省略すると接続元は空になるので、変更しない場合も現在の値を送ってください。
リソース
| メソッド | パス | 内容 |
|---|---|---|
POST |
/sites/{site}/resources |
リソースを作成（name、key、kind：content または collection） |
GET |
/resources/{resource} |
リソースの詳細（項目定義、下書きデータ、直近20件の公開履歴を含む） |
PUT |
/resources/{resource} |
名前と項目定義の下書きを保存（name、version、fields） |
DELETE |
/resources/{resource} |
リソースを削除（データ・公開履歴も削除） |
POST |
/resources/{resource}/publish |
保存済みの下書きを公開。レスポンスは {"version": "<公開版ID>"} |
POST |
/resources/{resource}/unpublish |
公開を停止 |
データ（レコード）
| メソッド | パス | 内容 |
|---|---|---|
POST |
/resources/{resource}/entries |
データを追加（key、values、position） |
PUT |
/resources/{resource}/entries/{entry} |
データを更新（key、values、position） |
DELETE |
/resources/{resource}/entries/{entry} |
データを削除 |
素材
| メソッド | パス | 内容 |
|---|---|---|
POST |
/sites/{site}/assets |
素材をアップロード（multipart の file、任意で is_public） |
DELETE |
/assets/{asset} |
素材を削除 |
データの受け渡し
| メソッド | パス | 内容 |
|---|---|---|
GET |
/sites/{site}/interchange/export |
管理用ZIPを書き出し |
POST |
/sites/{site}/interchange/preview |
ZIP（package）の内容を確認 |
POST |
/sites/{site}/interchange/import |
確認済みの内容を取り込み（token、confirm） |
詳しくは データの受け渡し（ZIP） をご覧ください。
過去の公開版への切り替え、素材の名前・公開設定の変更、APIトークンの発行・失効は管理画面でのみ行えます。
リクエストの詳細
項目定義の保存（PUT /resources/{resource}）
fieldsには項目定義の配列を全件送ります。送った内容で項目定義全体が置き換わります。- 各項目には
key、label、type、required、publicを指定します。select・radioではoptionsに{"value": "...", "label": "..."}の配列（または文字列の配列）を指定します。 - 任意で次の属性も指定できます。
| 属性 | 内容 |
|---|---|
description |
項目の説明（1000文字まで） |
min・max |
数値の下限・上限 |
minlength・maxlength |
文字数の下限・上限 |
nullable |
null を保存できるか（既定は「必須でなければ可」） |
nonempty |
空文字を禁止するか（既定は「必須なら禁止」） |
versionには、GET /resources/{resource}で取得した現在のversionを送ります。ほかの操作で更新されていた場合は 409 になります。データの保存・削除でもversionは進むので、項目定義を保存する直前に取得し直してください。- 型と値のルールは コンテンツとコレクション と同じです。フォーム専用の型（
checkboxes、file）は使えません。
データの保存（entries）
key、values、positionはすべて必須です。valuesは{"項目の識別キー": 値}のオブジェクトです。数値は数値、はい／いいえはtrue／false、リンクは文字列または{"url": "..."}で送ります。- コンテンツはデータが常に1件です。
POSTすると既存のデータが更新され、識別キーはmainになります。 - 保存先は下書きです。公開APIに反映するには
publishを呼びます。
例：お知らせを作って公開する
TOKEN='YOUR_TOKEN'
API='https://cms.magichtml.dev/api/v1'
# 1. コレクションを作成
curl -X POST "$API/sites/SITE_ID/resources" \
-H "Authorization: Bearer $TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"name": "お知らせ", "key": "news", "kind": "collection"}'
# => {"data": {"id": "RESOURCE_ID", ...}}
# 2. データを追加
curl -X POST "$API/resources/RESOURCE_ID/entries" \
-H "Authorization: Bearer $TOKEN" \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-d '{"key": "news-001", "position": 0, "values": {"title": "サイトを公開しました", "body": "本日よりサイトを公開しました。"}}'
# 3. 公開
curl -X POST "$API/resources/RESOURCE_ID/publish" \
-H "Authorization: Bearer $TOKEN" \
-H 'Accept: application/json'
# => {"version": "..."}
公開後は https://cms.magichtml.dev/api/public/v1/sites/SITE_ID/resources/news で取得できます。
レスポンスとエラー
成功時は、多くの場合 {"data": ...} の形で JSON を返します。サイト・リソース・素材の作成とデータの取り込みは 201、データ（レコード）の追加・更新は 200、削除と公開停止は本文なしの 204 です。
| ステータス | 主な原因 |
|---|---|
| 401 | トークンがない、誤っている、期限切れ |
| 404 | 対象が存在しない、または自分のサイトのものではない |
| 409 | 項目定義の version が古い（ほかの操作で更新済み） |
| 422 | 入力の検証エラー（message と errors を返します） |
| 429 | リクエスト数の上限を超えた |
所有者とアクセス範囲
- サイト、リソース、データ、素材は、それを作成したユーザーだけが操作できます。チームでの共有や権限の設定はありません。
- 他のユーザーのサイトやリソースを指定すると、存在しない場合と同じく 404 になります。
- 別のリソースに属するデータIDを指定した場合も 404 になります。
リクエスト数の上限
管理APIは、ユーザーごとに 1分あたり120リクエスト までです。超えると 429 を返します。