# Magic CMS 実装ガイド（AI向け）

このガイドは、AIアシスタントが Magic CMS（https://cms.magichtml.dev）の公開データを読み込んで表示するウェブサイトを作るための仕様です。人向けの説明は https://cms.magichtml.dev/docs にあります。

サイト運営者が管理画面の「AIへの指示」をコピーして渡している場合は、その指示に書かれたサイトID・キー・項目を最優先してください。このガイドは、その指示を補う一般的な規則です。

## 仕組み

- サイト運営者は Magic CMS の管理画面で、お知らせや紹介文などのデータを編集して「公開」します。
- ウェブサイトは、ページを開いたときに公開データを読み込んで表示します。ウェブサイトのHTMLを作り直さなくても、公開した内容が反映されます。
- データには2種類あります。「コンテンツ」は1件だけ（例：会社紹介）、「コレクション」は並び順のある複数件（例：お知らせ一覧）です。
- 読み込めるのは、管理画面で「公開」に設定された項目だけです。

## 必ずやること

1. ページの `</body>` 直前に、SDKを次のとおり読み込む（URL、integrity、crossorigin を変えない）：

```html
<script src="https://cdn.jsdelivr.net/npm/@magichtml/cms@0.1.0/magic-cms.js" integrity="sha384-bako2vxKJyzsf7errApVfA4Lk2QkaKDmAvws2+gV4giOGqHNEeZBeet+qTlJD2qh" crossorigin="anonymous"></script>
```

2. その後の script で `new MagicCMS('https://cms.magichtml.dev', 'サイトID')` を作り、`get('キー')` で読み込む。サイトIDとキーは管理画面の指示の値を使う。
3. 今のHTMLに書かれている内容は、読み込めなかったときの表示として残し、読み込めたら置き換える。
4. 文字列は `textContent` で入れる。`innerHTML` を使ってよいのは、型が `rich_text` または `document` の項目だけ。
5. 読み込みに失敗したとき（`catch`）は、元の内容を表示したままにする。

## やってはいけないこと

- 管理APIのトークンや管理画面のURLをページに書く。公開ページに必要なのはSDK、サイトID、キーだけです。
- `rich_text`・`document` 以外の値を `innerHTML` で入れる。
- SDKのファイルを自分のサイトにコピーして読み込む、または integrity を外す。
- 公開データの内容を、読み込まずにHTMLへ直接書き写す（管理画面で更新しても反映されなくなります）。読み込めなかったときの表示として残す内容は除きます。

## 読み込み結果の形

`cms.get(キー)` は次の形のオブジェクトを返します。

```json
{
  "version": "公開版のID",
  "name": "リソース名",
  "kind": "content または collection",
  "fields": [{ "key": "title", "label": "タイトル", "type": "text" }],
  "records": [{ "key": "main", "values": { "title": "…" } }],
  "pagination": { "page": 1, "per_page": 30, "total": 1 }
}
```

- コンテンツは `records[0].values` に値が入っています。
- コレクションは `records` が管理画面の並び順の配列です。`page` と `per_page`（1〜100、初期値30）で分割し、`pagination.total` で全件数がわかります。
- `q` を指定するとキーワードで絞り込み、`entry` にレコードのキーを指定するとその1件だけを取り出せます（詳細ページに使います）。

## 値の型と表示方法

| 型 | 値 | 表示方法 |
|---|---|---|
| text / email / tel / select / radio / hidden | 文字列 | `textContent` |
| textarea | 改行を含む文字列 | `textContent` と `white-space: pre-line` |
| rich_text / document | 許可されたタグだけのHTML（サーバーで検証済み） | `innerHTML` |
| number | 数値 | 書式を整えて `textContent` |
| boolean / checkbox | true / false | 表示の切り替えに使う |
| date | `YYYY-MM-DD` | 表示形式を整えて `textContent` |
| url | URL文字列 | `a` の `href` |
| link | `{ "url": "…" }` | `a` の `href` に `値.url` |
| asset | ファイルのURL。`/assets/` で始まる場合は相対パス | `new URL(値, 'https://cms.magichtml.dev')` で絶対URLにして `img` の `src` や `a` の `href` に使う |

値が空の項目は、`null` か、キー自体がないことがあります。どちらも空として扱ってください。

## 完成形の例（お知らせ一覧）

```html
<ul id="news">
  <li>2026-10-01 お知らせのタイトル（読み込めないときの表示）</li>
</ul>

<script src="https://cdn.jsdelivr.net/npm/@magichtml/cms@0.1.0/magic-cms.js" integrity="sha384-bako2vxKJyzsf7errApVfA4Lk2QkaKDmAvws2+gV4giOGqHNEeZBeet+qTlJD2qh" crossorigin="anonymous"></script>
<script>
  const cms = new MagicCMS('https://cms.magichtml.dev', 'SITE_ID');
  cms.get('news', { per_page: 10 }).then(data => {
    const list = document.getElementById('news');
    list.replaceChildren(...data.records.map(record => {
      const item = document.createElement('li');
      item.textContent = `${record.values.date ?? ''} ${record.values.title ?? ''}`;
      return item;
    }));
  }).catch(() => {});
</script>
```

## サイト運営者に伝えること

- 読み込むサイトのURL（例：`https://example.com`）を、管理画面の「サイト設定・接続元」に登録する必要があります。未登録のままだと読み込みが拒否されます。
- データを管理画面で公開していないと読み込めません。保存しただけの下書きは読み込まれません。

## 完成後の確認

1. ページを開き、公開データの内容が表示されること。
2. 管理画面で内容を変えて公開し、ページを再読み込みすると変更が反映されること。
3. ブラウザの開発者ツールのコンソールにエラーが出ていないこと。

## うまくいかないとき

| 症状 | 原因と直し方 |
|---|---|
| 読み込みが失敗し、コンソールに CORS のエラーが出る | 読み込むサイトのURLが接続元に未登録。運営者に登録を依頼する |
| 404 になる | サイトIDかキーが違う、またはデータが未公開 |
| 値が表示されない | その項目が非公開に設定されている、またはキーが違う |
| 画像が表示されない | `/assets/` で始まる値を絶対URLにしていない、または素材が非公開 |

---

# はじめに

Magic CMS Cloud は、静的サイトに「あとから編集できる文章や一覧」を届けるホスト型の CMS です。管理画面でコンテンツやコレクションを作って値を下書きし、明示的に「公開」した内容だけを、静的サイトが公開API または CMS SDK（`@magichtml/cms`）で読み込みます。サーバーやデータベースを自分で用意する必要はありません。

## できること

| 機能 | 内容 |
|---|---|
| コンテンツ | 会社概要・ページ本文など、1件だけのデータを管理します。 |
| コレクション | お知らせ・実績など、並び順を持つ複数件のデータを管理します。検索とページ分けに対応します。 |
| 下書きと公開 | 保存は下書きにだけ反映されます。「公開」した時点の内容が公開版になり、過去の公開版へ戻すこともできます。 |
| 素材ライブラリ | 画像・PDF・動画・音声などをサイトごとに保管し、公開URLで配信できます。 |
| 公開API／SDK | 認証なしで公開版を読み取れます。読み込みを許可するサイトの接続元（Origin）を登録します。 |
| データの受け渡し | サイトのデータを `.magichtml.zip` で書き出し、別のサイトや対応アプリケーションに取り込めます。 |

フォームの受信は扱いません。お問い合わせフォームなどは、別製品の Magic Form Cloud をご利用ください。

## 利用の流れ

1. **招待からログインする**　Magic CMS Cloud は招待制です。一般公開の新規登録はありません。サービス管理者から届いた招待URLを開き、お名前・メールアドレス・パスワード（英字と数字を含む12文字以上）を設定します。招待URLは1回だけ使え、有効期限は24時間です。以降はメールアドレスとパスワードでログインします。パスワードの再設定はサービス管理者へご連絡ください。
2. **サイトを作成する**　ログイン後のサイト一覧（`https://cms.magichtml.dev/app`）で「＋ サイトを作成」を押し、サイト名を入力します。サイトは、静的サイト1つ分のデータのまとまりです。
3. **コンテンツ／コレクションを作成する**　サイト画面の「＋ 新規作成」で種類・名前・識別キー（例：`news`）を決めます。識別キーは公開APIのURLやSDKで使う名前です。詳しくは [コンテンツとコレクション](/docs/resources) をご覧ください。
4. **項目と値を下書き保存する**　「項目・設定」タブで項目（タイトル・本文・日付など）を定義し、「データ」タブで値を入力して保存します。どちらも下書きとして保存され、公開中の内容は変わりません。
5. **公開する**　「保存済みの下書きを公開」を押すと、その時点の下書きが新しい公開版になり、公開APIから取得できるようになります。
6. **接続元（Origin）を登録する**　サイト画面の「サイト設定・接続元」に、静的サイトのURL（例：`https://example.com`）を1行に1件登録します。ブラウザから公開APIを読み込むには、この登録が必要です。
7. **サイトから読み込む**　静的サイトに CMS SDK を読み込み、公開版のデータを表示します。

## 下書きと公開版

| | 下書き | 公開版 |
|---|---|---|
| 作られるとき | 項目や値を保存したとき | 「保存済みの下書きを公開」を押したとき |
| 公開APIでの取得 | できません | できます（公開項目のみ） |
| 変更 | 何度でも上書きできます | 変更できません。公開のたびに新しい版が作られます |

- 公開後に下書きを編集しても、再度公開するまで静的サイトの表示は変わりません。
- リソース画面の「接続・公開履歴」タブに公開履歴（新しい順に最大20件）が表示されます。過去の版の「この版を公開」を押すと、公開版をその版に切り替えられます（ロールバック）。下書きは変更されません。
- 「公開停止」を押すと公開APIから取得できなくなります。下書きと公開履歴は残ります。

## 最小構成の例

次の HTML は、識別キー `about` のコンテンツを読み込み、`title` と `body` を表示します。`SITE_ID` はサイトのIDに置き換えてください。サイトIDは、サイト画面の「静的サイトとの接続」にある公開接続先URL（`https://cms.magichtml.dev/api/public/v1/sites/<サイトID>`）や、リソース画面の「接続・公開履歴」タブの接続サンプルで確認できます。

```html
<!doctype html>
<html lang="ja">
<head>
  <meta charset="utf-8">
  <title>会社概要</title>
</head>
<body>
  <h1 id="title">読み込み中…</h1>
  <p id="body"></p>

  <script src="https://cdn.jsdelivr.net/npm/@magichtml/cms@0.1.0/magic-cms.js" integrity="sha384-bako2vxKJyzsf7errApVfA4Lk2QkaKDmAvws2+gV4giOGqHNEeZBeet+qTlJD2qh" crossorigin="anonymous"></script>
  <script>
    const cms = new MagicCMS('https://cms.magichtml.dev', 'SITE_ID');
    cms.get('about').then(data => {
      const values = data.records[0].values;
      document.getElementById('title').textContent = values.title;
      document.getElementById('body').textContent = values.body ?? '';
    }).catch(error => {
      console.error(error.status, error.message);
    });
  </script>
</body>
</html>
```

動作させる前に、次の3点を確認してください。

- `about` のコンテンツに値を保存し、公開していること（未公開の場合は 404 になります）。
- 表示するページのオリジン（例：`https://example.com`）を接続元に登録していること。
- `title` と `body` の項目が「公開」になっていること（非公開の項目はAPIに含まれません）。

各リソース画面の「接続・公開履歴」タブには、サイトIDと識別キーを埋め込んだ接続サンプルが表示されます。コピーして使うと確実です。

## 次に読むページ

- [コンテンツとコレクション](/docs/resources)：項目の型・値のルール・公開の操作
- [公開API](/docs/public-api)：レスポンス形式・検索・ページ分け・CORS
- [CMS SDK](/docs/sdk)：SDK の読み込み方と使い方
- [素材ライブラリ](/docs/assets)：画像やファイルの配信
- [データの受け渡し（ZIP）](/docs/interchange)：書き出しと取り込み
- [管理API](/docs/management-api)：APIトークンによる自動化

---

# コンテンツとコレクション

Magic CMS Cloud では、サイトの中に「リソース」を作ってデータを管理します。リソースには、1件だけのデータを持つ「コンテンツ」と、並び順を持つ複数件のデータを持つ「コレクション」の2種類があります。このページでは、リソースの作り方、項目の型と値のルール、公開・公開停止・過去の版への切り替え・削除について説明します。

## 2つの種類

| 種類 | 値 | データ件数 | 主な用途 |
|---|---|---|---|
| コンテンツ | `content` | 1件 | 会社概要、トップページの見出し、フッターの文言 |
| コレクション | `collection` | 複数件（並び順あり） | お知らせ、実績、スタッフ紹介、FAQ |

フォームはリソースとして作成できません。フォームは別製品の Magic Form Cloud で管理します。

## リソースを作成する

サイト画面の「＋ 新規作成」から、次の3つを入力します。

| 入力 | ルール |
|---|---|
| 種類 | コンテンツ または コレクション |
| 名前 | 管理画面に表示される名前（例：お知らせ） |
| 識別キー | 英小文字で始まり、英小文字・数字・`_`・`-` のみ。80文字まで。サイト内で重複不可（例：`news`） |

識別キーは公開APIのURL（`/api/public/v1/sites/SITE_ID/resources/news`）や SDK の `cms.get('news')` で使います。

作成直後のリソースには、次の2項目があらかじめ用意されています。

| 識別キー | 項目名 | 型 | 必須 | 公開 |
|---|---|---|---|---|
| `title` | タイトル | テキスト | はい | はい |
| `body` | 本文 | 複数行 | いいえ | はい |

## 項目を定義する

リソース画面の「項目・設定」タブで項目を追加・変更し、「項目・設定の下書きを保存」を押します。1リソースあたり最大100項目です。

| 列 | 説明 |
|---|---|
| 識別キー | 英字で始まり、英数字・`_`・`-` のみ、128文字まで。リソース内で重複不可。APIの `values` のキーになります。 |
| 項目名 | 管理画面での表示名（255文字まで）。下に任意の「説明」（1000文字まで）を付けられます。 |
| 型 | 下表の型から選びます。 |
| 必須 | オンにすると、値の省略や空の値を保存できません。 |
| 公開 | オンの項目だけが公開APIで返されます。 |
| 選択候補 | 「選択」「単一選択」で使う候補。1行に `値 | 表示名` の形式で入力します（`|` を省くと値と表示名が同じになります）。 |

項目の定義を保存すると、リソースの版番号が進みます。別の画面や管理APIで同時に更新されていた場合は保存が拒否されるので（「別の操作で更新されています。」）、再読み込みしてから操作し直してください。

## 項目の型と値のルール

| 管理画面の表示 | 型の値 | 保存できる値 | 公開APIでの形 |
|---|---|---|---|
| テキスト | `text` | 文字列 | 文字列 |
| 複数行 | `textarea` | 文字列 | 文字列 |
| メール | `email` | メールアドレス形式の文字列 | 文字列 |
| URL | `url` | `http://` または `https://` で始まり空白を含まない文字列 | 文字列 |
| 数値 | `number` | 数値 | 数値 |
| はい／いいえ | `boolean` | はい または いいえ | `true` / `false` |
| 日付 | `date` | `YYYY-MM-DD` 形式の実在する日付 | 文字列 |
| 選択 | `select` | 選択候補の値のいずれか | 文字列 |
| 単一選択 | `radio` | 選択候補の値のいずれか | 文字列 |
| 同意 | `checkbox` | はい または いいえ（必須にすると「はい」のみ） | `true` / `false` |
| 電話番号 | `tel` | 文字列 | 文字列 |
| 非表示 | `hidden` | 文字列 | 文字列 |
| 装飾文（HTML） | `rich_text` | 許可されたタグだけで書いた HTML | 文字列（HTML） |
| 文書（HTML） | `document` | 許可されたタグだけで書いた HTML | 文字列（HTML） |
| 素材URL | `asset` | `http://`・`https://` で始まるURL、または `/assets/` で始まるパス | 文字列 |
| リンク | `link` | 安全なリンク先（下記） | `{"url": "..."}` |

共通のルールは次のとおりです。

- 文字列の値は100,000文字までです。
- メール・URL・日付・選択などの形式チェックは、値が空でないときに行われます。
- 必須でない「数値」「リンク」を空欄で保存すると、値は `null` になります。
- 定義にない識別キーの値は保存できません。

### 装飾文・文書（HTML）で使えるタグ

保存時に HTML が検証され、許可されていない要素や属性があると保存できません（自動で取り除くことはしません）。

- 要素：`p` `br` `strong` `em` `b` `i` `u` `s` `del` `ins` `sub` `sup` `span` `a` `code` `pre` `blockquote` `ul` `ol` `li` `h1`〜`h6` `hr` `table` `thead` `tbody` `tfoot` `tr` `th` `td` `caption`
- 属性：`href` `title` `colspan` `rowspan` `scope` `start` `reversed`
- `script`・`style`・`img` などの要素、`class`・`style`・イベント属性は使えません。

### リンク先として使える値

「リンク」型の値と、HTML の `href` には次の形式が使えます。

- `http://` または `https://` で始まるURL
- `mailto:`、`tel:`、`#` で始まる値
- `/` で始まるサイト内パス（`//` で始まるものを除く）

## 公開項目と非公開項目

「公開」がオフの項目は、管理画面と管理APIでだけ扱える項目です。社内メモや下書き用の情報に使えます。

- 公開API・SDK のレスポンスでは、`fields` と各レコードの `values` から除かれます。
- 公開APIの検索（`q`）の対象にもなりません。除外したうえで検索・ページ分けが行われます。
- 公開・非公開の設定は公開版に記録されます。設定を変えたら、もう一度公開すると反映されます。
- [データの受け渡し（ZIP）](/docs/interchange) の書き出しファイルには非公開項目も含まれます。

## データ（レコード）を保存する

「データ」タブで値を入力し、「データを保存」を押します。保存先は下書きです。

| 入力 | ルール |
|---|---|
| 識別キー | 英数字で始まり、英数字・`_`・`-` のみ、180文字まで。リソース内で重複不可（例：`news-001`）。公開APIの `entry` パラメーターで1件を指定するときに使います。 |
| 並び順 | -1,000,000〜1,000,000 の整数。小さい順に並び、同じ値なら識別キー順です。 |

- コンテンツのデータは常に1件で、識別キーは `main` に固定されます。
- コレクションは「＋ データを追加」で何件でも追加できます。新規追加時の並び順には、既存の件数が初期値として入ります。
- 「削除」を押すと下書きからそのデータが消えます。公開中の版から消すには、再度公開してください。

## 公開する

リソース画面上部の「保存済みの下書きを公開」を押すと、保存済みの項目定義とデータがそのまま新しい公開版になり、すぐに公開APIで返されるようになります。画面上で保存していない入力は含まれません。

- 公開時に、すべてのデータが現在の項目定義に合っているか検証されます。項目の型や必須を変えた後に、古いデータが合わなくなっていると公開できません。データを直してから公開してください。
- コンテンツは、データを保存してからでないと公開できません。
- 項目の構成（識別キーや型）を変えて公開すると、静的サイト側の表示処理も合わせて直す必要がある場合があります。

## 公開を停止する

「公開停止」を押すと、そのリソースは公開APIから取得できなくなります（404）。下書きと公開履歴は残るので、再び公開したり、過去の版を公開したりできます。

## 過去の公開版に切り替える

「接続・公開履歴」タブに、公開日時と版IDの先頭8文字が新しい順に最大20件表示されます。現在の版には「公開中」と表示されます。ほかの版の「この版を公開」を押すと、公開版がその版に切り替わります。

- 下書きは変更されません。切り替え後に「保存済みの下書きを公開」を押すと、下書きの内容が新しい版として公開されます。
- 切り替えは管理画面でのみ行えます（管理APIにはありません）。

## リソースを削除する

リソース画面下部の「リソースを削除」から削除します。データ・公開履歴もあわせて削除され、公開APIからも取得できなくなります。元に戻せません。

サイトを削除した場合は、サイト内のすべてのリソース・公開履歴・素材が削除されます。

## 関連ページ

- [公開API](/docs/public-api)
- [CMS SDK](/docs/sdk)
- [素材ライブラリ](/docs/assets)

---

# 公開API

公開APIは、公開中のコンテンツ・コレクションを認証なしで読み取るための読み取り専用APIです。返すのは「公開」した版の公開項目だけで、下書きや非公開項目は含まれません。ブラウザからは登録済みの接続元（Origin）からのみ読み込めます。通常は [CMS SDK](/docs/sdk) から利用しますが、直接呼び出すこともできます。

## エンドポイント

```
GET https://cms.magichtml.dev/api/public/v1/sites/{site}/resources/{key}
```

| パラメーター | 説明 |
|---|---|
| `{site}` | サイトID（UUID）。サイト画面の公開接続先URLや、リソース画面の「接続・公開履歴」タブで確認できます。 |
| `{key}` | リソースの識別キー（例：`news`） |

APIトークンやログインは不要です。管理APIのトークンを公開サイトに埋め込まないでください。

```sh
curl 'https://cms.magichtml.dev/api/public/v1/sites/SITE_ID/resources/news?page=1&per_page=10'
```

## レスポンス

```json
{
  "version": "9d3f2c1e-5b7a-4c2e-8f10-2a6b7c8d9e0f",
  "name": "お知らせ",
  "kind": "collection",
  "fields": [
    {"key": "title", "label": "タイトル", "type": "text", "required": true, "public": true},
    {"key": "body", "label": "本文", "type": "textarea", "required": false, "public": true}
  ],
  "records": [
    {"key": "news-002", "values": {"body": "新しいサービスを開始しました。", "title": "サービス開始のお知らせ"}},
    {"key": "news-001", "values": {"body": "営業時間を変更します。", "title": "営業時間変更"}}
  ],
  "pagination": {"page": 1, "per_page": 30, "total": 2}
}
```

| キー | 内容 |
|---|---|
| `version` | 現在公開中の版のID。公開や版の切り替えのたびに変わります。 |
| `name` | リソース名（公開した時点のもの） |
| `kind` | `content` または `collection` |
| `fields` | 公開項目の定義（識別キー・項目名・型・必須・公開など）。非公開項目は含まれません。 |
| `records` | レコードの配列。各要素は `key`（レコードの識別キー）と `values`（公開項目の値）を持ちます。 |
| `pagination` | `page`（ページ番号）、`per_page`（1ページの件数）、`total`（絞り込み後の総件数） |

- レコードは並び順の小さい順（同じなら識別キー順）に並びます。
- コンテンツはレコードが1件（識別キー `main`）なので、`records[0].values` で値を取り出せます。
- 値の形は項目の型によって異なります（数値は数値、はい／いいえは `true`／`false`、リンクは `{"url": "..."}`、それ以外は文字列）。値を保存していない任意項目は `values` に含まれないか `null` になります。詳しくは [コンテンツとコレクション](/docs/resources) をご覧ください。

## クエリパラメーター

| パラメーター | 既定値 | 説明 |
|---|---|---|
| `q` | なし | 検索語。公開項目の値に部分一致するレコードに絞り込みます（英字の大文字・小文字は区別しません）。先頭200文字までが使われます。 |
| `entry` | なし | レコードの識別キー。一致する1件に絞り込みます（完全一致）。 |
| `page` | `1` | ページ番号。1未満は1として扱います。 |
| `per_page` | `30` | 1ページの件数。1〜100の範囲に丸められます（101以上を指定しても100件）。 |

- 絞り込みは `q`、`entry` の順に行われ、その結果に対してページ分けが行われます。`pagination.total` は絞り込み後の件数です。
- 範囲外のページを指定すると、`records` は空配列になります。
- これらのパラメーターはコンテンツにも使えますが、主にコレクションの一覧・詳細表示で使います。

```sh
# 「採用」を含むお知らせの2ページ目（1ページ10件）
curl 'https://cms.magichtml.dev/api/public/v1/sites/SITE_ID/resources/news?q=採用&page=2&per_page=10'

# 識別キー news-001 のお知らせ1件
curl 'https://cms.magichtml.dev/api/public/v1/sites/SITE_ID/resources/news?entry=news-001'
```

## 非公開項目の扱い

「公開」をオフにした項目は、レスポンスを作る前に取り除かれます。

- `fields` に定義が含まれず、`records[].values` に値も含まれません。
- 検索（`q`）は非公開項目を除いた値に対して行われるため、非公開項目の内容で検索しても一致しません。
- 公開・非公開の設定は公開版ごとに記録されています。設定を変えたら再度公開してください。

## CORS と接続元（Origin）

ブラウザ上の JavaScript から読み込む場合、そのページのオリジンをサイトの「許可する接続元」に登録する必要があります。

- サイト画面の「サイト設定・接続元」に、1行に1件ずつ入力します（例：`https://example.com`）。
- `http://` または `https://` で始まり、パス・クエリ・`#`・ユーザー名を含まない形式で入力します。末尾の `/` は自動で取り除かれます。
- ワイルドカード（`*`）は使えません。最大20件です。
- ブラウザが送る `Origin` と完全に一致する必要があります。`https://example.com` と `https://www.example.com`、ポート番号の有無は別の接続元として扱われます。

| 状況 | 結果 |
|---|---|
| 登録済みの接続元からのリクエスト | `Access-Control-Allow-Origin` にそのオリジンを返します。 |
| 未登録の接続元からのリクエスト | 403（「この接続元は許可されていません。」）。CORS ヘッダーが付かないため、ブラウザでは通信エラーになります。 |
| `Origin` ヘッダーのないリクエスト（curl、サーバー側の処理など） | 制限なく読み取れます。 |

許可されるメソッドは `GET` と `OPTIONS`、リクエストヘッダーは `Content-Type` と `Accept` です。Cookie などの資格情報は使いません。

## エラー

エラー時は JSON の `message` を含むレスポンスを返します。

| ステータス | 主な原因 |
|---|---|
| 403 | 接続元が許可されていない |
| 404 | サイトIDが存在しない、識別キーのリソースがない、またはリソースが公開されていない（未公開・公開停止中） |
| 429 | リクエスト数の上限を超えた |

## リクエスト数の上限

公開APIは、送信元IPアドレスごとに **1分あたり120リクエスト** までです。超えると 429 を返します。ページを表示するたびに同じリソースを何度も読み込まないよう、1ページ内での呼び出しはまとめてください。

## キャッシュ

公開APIのレスポンスには `Cache-Control: no-store` が付きます。ブラウザや中継サーバーにキャッシュされないため、公開・公開停止・版の切り替えは次のリクエストからすぐに反映されます。

## 関連ページ

- [CMS SDK](/docs/sdk)
- [コンテンツとコレクション](/docs/resources)

---

# CMS SDK

CMS SDK（npm パッケージ `@magichtml/cms`）は、[公開API](/docs/public-api) をブラウザから簡単に呼び出すための小さな JavaScript ライブラリです。通常の `<script>` タグで読み込むと `window.MagicCMS` が使えるようになり、`get()` で公開中のコンテンツやコレクションを取得できます。管理用の認証情報は受け付けず、必要もありません。

## 読み込み方

バージョンを固定した URL と SRI（`integrity`）ハッシュを指定して、クラシックな `<script>` タグで読み込みます（`type="module"` は不要です）。

```html
<script src="https://cdn.jsdelivr.net/npm/@magichtml/cms@0.1.0/magic-cms.js" integrity="sha384-bako2vxKJyzsf7errApVfA4Lk2QkaKDmAvws2+gV4giOGqHNEeZBeet+qTlJD2qh" crossorigin="anonymous"></script>
```

- 各リソース画面の「接続・公開履歴」タブにある「接続サンプル」に、現在のバージョンとハッシュを入れたタグが表示されます。
- SDK は jsDelivr から配信されます。`integrity` を付けると、配信されたファイルが改ざんされていないことをブラウザが確認します。
- SDK を使うページのオリジンを、サイトの「許可する接続元」に登録してください（[公開API](/docs/public-api) の「CORS と接続元」を参照）。

## クライアントを作る

```js
const cms = new MagicCMS('https://cms.magichtml.dev', 'SITE_ID');
```

| 引数 | 説明 |
|---|---|
| `baseUrl` | Magic CMS Cloud のURL。`http:` または `https:` のURLを指定します。オリジン部分だけが使われ、パスは無視されます。それ以外の形式では `Invalid endpoint` エラーになります。 |
| `siteId` | サイトID（UUID）。サイト画面の公開接続先URLや、リソース画面の接続サンプルで確認できます。 |

## データを取得する：`get(key, query)`

```js
const data = await cms.get('news', {page: 1, per_page: 10});
```

- `key`：リソースの識別キー
- `query`：省略可能。`q`、`entry`、`page`、`per_page` を指定できます。値が `undefined`・`null`・空文字の項目は送信されません。
- 戻り値：`{version, name, kind, fields, records, pagination}` に解決される Promise。形式は [公開API](/docs/public-api) のレスポンスと同じです。
- リクエストは資格情報（Cookie）なしで送られます。

### 例：コンテンツを表示する

```html
<h1 data-cms="title"></h1>
<div data-cms="lead"></div>

<script src="https://cdn.jsdelivr.net/npm/@magichtml/cms@0.1.0/magic-cms.js" integrity="sha384-bako2vxKJyzsf7errApVfA4Lk2QkaKDmAvws2+gV4giOGqHNEeZBeet+qTlJD2qh" crossorigin="anonymous"></script>
<script>
  const cms = new MagicCMS('https://cms.magichtml.dev', 'SITE_ID');
  cms.get('about').then(data => {
    const values = data.records[0].values;
    for (const element of document.querySelectorAll('[data-cms]')) {
      element.textContent = values[element.dataset.cms] ?? '';
    }
  });
</script>
```

### 例：検索とページ分けのあるお知らせ一覧

```html
<form id="search">
  <input name="q" type="search" placeholder="キーワード">
  <button>検索</button>
</form>
<ul id="news"></ul>
<nav>
  <button id="prev" type="button">前へ</button>
  <span id="page"></span>
  <button id="next" type="button">次へ</button>
</nav>
<p id="error" hidden>お知らせを読み込めませんでした。</p>

<script src="https://cdn.jsdelivr.net/npm/@magichtml/cms@0.1.0/magic-cms.js" integrity="sha384-bako2vxKJyzsf7errApVfA4Lk2QkaKDmAvws2+gV4giOGqHNEeZBeet+qTlJD2qh" crossorigin="anonymous"></script>
<script>
  const cms = new MagicCMS('https://cms.magichtml.dev', 'SITE_ID');
  const state = {q: '', page: 1, per_page: 10};

  async function render() {
    try {
      const data = await cms.get('news', state);
      const list = document.getElementById('news');
      list.replaceChildren(...data.records.map(record => {
        const li = document.createElement('li');
        const link = document.createElement('a');
        link.href = 'detail.html?id=' + encodeURIComponent(record.key);
        link.textContent = record.values.title;
        li.append(link);
        return li;
      }));
      const {page, per_page, total} = data.pagination;
      const pages = Math.max(1, Math.ceil(total / per_page));
      document.getElementById('page').textContent = page + ' / ' + pages;
      document.getElementById('prev').disabled = page <= 1;
      document.getElementById('next').disabled = page >= pages;
      document.getElementById('error').hidden = true;
    } catch (error) {
      document.getElementById('error').hidden = false;
      console.error(error.status, error.message);
    }
  }

  document.getElementById('search').addEventListener('submit', event => {
    event.preventDefault();
    state.q = new FormData(event.target).get('q');
    state.page = 1;
    render();
  });
  document.getElementById('prev').addEventListener('click', () => { state.page--; render(); });
  document.getElementById('next').addEventListener('click', () => { state.page++; render(); });
  render();
</script>
```

### 例：1件を表示する（詳細ページ）

`entry` にレコードの識別キーを指定すると、その1件だけを取得できます。

```js
const id = new URLSearchParams(location.search).get('id');
const data = await cms.get('news', {entry: id});
const record = data.records[0];
if (record) {
  document.querySelector('h1').textContent = record.values.title;
}
```

### 値の表示についての注意

- テキストなどの値は `textContent` で挿入してください。
- 「装飾文（HTML）」「文書（HTML）」の値は、許可されたタグ・属性だけで構成されていることが保存時に検証された HTML 文字列です。HTML として表示する場合は `innerHTML` などで挿入します。
- 「リンク」型の値は `{url: '...'}` の形です。
- 「素材URL」型の値が `/assets/` で始まるパスの場合は、`'https://cms.magichtml.dev' + value` のように Magic CMS Cloud のURLを前に付けてください（[素材ライブラリ](/docs/assets) を参照）。

## エラー処理

取得に失敗すると、Promise は `Error` で reject されます。

| プロパティ | 内容 |
|---|---|
| `status` | HTTP ステータス（例：404、429） |
| `message` | サーバーが返したメッセージ。ない場合は `Magic CMS request failed` |

```js
try {
  const data = await cms.get('news');
} catch (error) {
  if (error.status === 404) {
    // リソースがない、または公開されていない
  } else if (error.status === 429) {
    // リクエスト数の上限。時間をおいて再試行
  } else if (error.status === undefined) {
    // ネットワークエラー、または接続元が許可されていない（CORS）
  }
}
```

接続元が登録されていない場合、ブラウザは応答を読み取れないため、`status` のない通信エラーになります。開発者ツールのコンソールに CORS のエラーが出ていないか確認してください。

API が使えない場合に備えて、静的HTMLに初期の文言を書いておき、取得できたときだけ置き換える構成にすると安全です。

## バージョンの確認：`MagicCMS.VERSION`

読み込んだ SDK のバージョンを文字列で返します。

```js
console.log(MagicCMS.VERSION); // 例: "0.1.0"
```

## バージョンの方針

- 常にバージョンを固定した URL と `integrity` ハッシュを使ってください。
- `magic-cms.js` を変更するときは必ず新しいバージョンとして公開されます。一度公開されたバージョンのファイルは変わりません。
- 新しいバージョンに切り替えるときは、リソース画面の接続サンプルに表示される URL とハッシュの組み合わせに、両方まとめて差し替えてください。片方だけ変えると、ブラウザは SDK を読み込みません。

## そのほか

- SDK は CommonJS 形式でも読み込めます（`require('@magichtml/cms')`）。サーバー側から公開データを取得する場合などに使えます。
- 第3引数で `fetch` の実装を渡せます（`new MagicCMS(baseUrl, siteId, {fetch: myFetch})`）。

## 関連ページ

- [公開API](/docs/public-api)
- [はじめに](/docs/getting-started)

---

# 素材ライブラリ

素材ライブラリは、サイトごとに画像・PDF・テキスト・動画・音声のファイルを保管する場所です。アップロードした素材は「公開」にすると誰でも取得できるURLで配信され、コンテンツやコレクションの値から参照できます。非公開の素材は、ログイン中の所有者だけが取得できます。

## アップロードする

サイト画面の「素材ライブラリ」を開き、ファイルを選んで「アップロード」を押します。

| 項目 | 内容 |
|---|---|
| 使えるファイル | 画像（JPEG `.jpg` `.jpeg`、PNG `.png`、GIF `.gif`、WebP `.webp`）、PDF `.pdf`、テキスト `.txt`、動画（MP4 `.mp4`、WebM `.webm`）、音声（MP3 `.mp3`、WAV `.wav`） |
| サイズ | 1ファイル 20 MB まで |
| 公開設定 | 「公開URLで取得可能にする」にチェックすると公開素材になります。チェックしない場合は非公開です（初期状態）。 |
| 名前 | アップロードしたファイル名がそのまま素材名になります。 |

SVG はアップロードできません。

## 名前と公開設定を変える

素材の一覧で名前（255文字まで）を書き換えたり、「公開」のチェックを切り替えたりして「保存」を押します。名前は、素材をダウンロードしたときのファイル名として使われます。素材のURLは変わりません。

## 公開URL

各素材の「取得」リンクが、その素材のURLです。

```
https://cms.magichtml.dev/assets/<素材ID>
```

| 公開設定 | 取得できる人 |
|---|---|
| 公開 | 誰でも（ログイン不要） |
| 非公開 | その素材を持つサイトの所有者（ログイン中）のみ。それ以外は 404 になります。 |

配信のされ方は次のとおりです。

- 画像・動画・音声はブラウザ内で表示・再生されます。PDF とテキストはダウンロードとして配信されます。
- レスポンスには `Cache-Control: no-store` が付くため、公開設定の変更や削除はすぐに反映されます。
- 素材は `X-Frame-Options: DENY` 付きで配信されるため、`<iframe>` の中には表示できません。画像は `<img>`、動画は `<video>`、音声は `<audio>` で参照してください。

## コンテンツの値から参照する

素材を静的サイトに表示するには、素材を「公開」にしたうえで、そのURLをコンテンツやコレクションの値に入れます。

1. 素材ライブラリで素材を「公開」にします。
2. 「取得」リンクのURLをコピーします。
3. リソースの「素材URL」型の項目に、そのURLを入力して保存し、公開します。

```js
const cms = new MagicCMS('https://cms.magichtml.dev', 'SITE_ID');
const data = await cms.get('about');
const image = document.querySelector('#hero');
const src = data.records[0].values.hero_image;
// /assets/ で始まるパスの場合は Magic CMS Cloud のURLを前に付けます
image.src = src.startsWith('/') ? 'https://cms.magichtml.dev' + src : src;
```

- 「素材URL」型には、`http://`・`https://` で始まるURL、または `/assets/` で始まるパスを保存できます。
- [データの受け渡し（ZIP）](/docs/interchange) で取り込んだ素材への参照は、`/assets/<素材ID>` の形のパスになります。静的サイトのページから参照するときは、上の例のように `https://cms.magichtml.dev` を前に付けてください。
- 「装飾文（HTML）」「文書（HTML）」の `<a href>` や「リンク」型の値から素材のURLを指すこともできます（PDF のダウンロードリンクなど）。
- 非公開の素材を参照しても、静的サイトの訪問者には表示されません。

## 削除する

素材の「削除」を押すと、ファイルと素材の情報が削除されます。その素材を参照しているURLは使えなくなる（404 になる）ため、先にコンテンツ側の参照を差し替えてから削除してください。サイトを削除した場合も、そのサイトの素材はすべて削除されます。

## 管理APIでの操作

[管理API](/docs/management-api) では、素材のアップロードと削除ができます（名前と公開設定の変更は管理画面で行います）。

```sh
curl -X POST 'https://cms.magichtml.dev/api/v1/sites/SITE_ID/assets' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -F 'file=@hero.jpg' \
  -F 'is_public=1'
```

レスポンスの `data.id` が素材IDです。

---

# データの受け渡し（ZIP）

「データの受け渡し」では、サイトのコンテンツ・コレクションを `.magichtml.zip` 形式の管理用ZIPに書き出したり、ZIPを取り込んで新しいリソースとして追加したりできます。サイトの複製や、MagicHTML 形式に対応した別のアプリケーションとのデータの移し替えに使います。取り込みは同期ではなくコピーで、取り込んだデータはそれぞれのシステムで独立して管理されます。

サイト画面の「データの受け渡し」から開きます。

## 書き出す

「管理用ZIPをダウンロード」を押すと、`site.magichtml.zip` がダウンロードされます。

| 含まれるもの | 含まれないもの |
|---|---|
| サイト名 | 公開状態・公開履歴 |
| すべてのコンテンツ・コレクションの項目定義（非公開項目を含む） | 許可する接続元などのサイト設定 |
| 保存済みの下書きデータ（値・識別キー・並び順） | アカウント・パスワード・APIトークン |
| データから参照されている素材ライブラリのファイル | どこからも参照されていない素材、素材の公開設定 |

- 書き出されるのは保存済みの下書きです。公開中の版ではありません。
- 値の中で `/assets/<素材ID>` や `https://cms.magichtml.dev/assets/<素材ID>` の形で参照されている素材が、ZIPに同梱されます。
- ほかのサイトの素材や、存在しない素材を参照している場合は書き出せません。
- 非公開項目の値も含まれるため、ZIPは管理用ファイルとして扱い、公開サイトのフォルダには置かないでください。

## 取り込む

取り込みは「内容の確認」と「取り込みの実行」の2段階です。

1. 「MagicHTML ZIP」でZIPファイルを選び、「内容を確認」を押します。
2. ZIPの検証が行われ、問題がなければ取り込む内容が表示されます。
   - パッケージ名、素材の件数
   - 各リソースの種類・名前・識別キー・項目数・レコード数
3. 内容を確認し、「内容を確認し、新規コピーとして取り込みます」にチェックして「下書きとして取り込む」を押します。

確認結果は **30分間** 有効で、1回だけ使えます。確認した本人・確認したサイトでのみ使えます。期限が切れた場合は、ZIPを選び直してください。

### 取り込み後の状態

| 対象 | 状態 |
|---|---|
| リソース | 新しいリソースとして追加され、**未公開** の下書きになります。 |
| データ | ZIP内の値・識別キー・並び順がそのまま下書きデータになります。 |
| 素材 | 素材ライブラリに追加され、**非公開** になります。 |
| 素材への参照 | 新しい素材を指す `/assets/<素材ID>` のパスに書き換えられます。 |

内容・項目・素材を確認したうえで、必要な素材を「公開」にし、各リソースを公開してください。接続元の登録も必要に応じて行ってください。

### 識別キーの重複

ZIP内のリソースと同じ識別キーのリソースが取り込み先のサイトにあると、取り込みは中止されます（一部だけ取り込まれることはありません）。上書きや統合はできないため、新しいサイトや空のサイトに取り込むか、既存のリソースを整理してから取り込んでください。

### フォームは取り込まれません

フォームは別製品の Magic Form Cloud で管理します。ZIPにフォームが含まれていても、エラーにはならずにスキップされます。確認画面では「フォームは Magic Form Cloud で管理します（取り込みません）」と表示され、フォームの識別キーは重複チェックの対象にもなりません。書き出しにもフォームは含まれません。

## 制限

| 項目 | 上限 |
|---|---|
| ZIPファイルのサイズ | 50 MB |
| 展開後の合計サイズ | 50 MB |
| ZIP内のファイル数 | 202（`manifest.json`、`resources.json`、素材200件） |
| 素材 | 200件 |
| リソース | 200件 |
| 1リソースあたりの項目 | 100件 |
| 1リソースあたりのレコード | 1,000件 |
| JSONファイル | 1ファイル 5 MB |

ZIPファイルは50 MBまでアップロードできます。それを超える場合は 413 で拒否されます。

同梱できる素材の形式は PNG・JPEG・WebP・GIF・PDF・テキスト・MP4・WebM・MP3・WAV です。ファイルの中身と宣言された形式が一致しない素材は取り込めません。

次のようなZIPは、内容の確認の段階でエラーになります。

- 対応していない形式・バージョン（対応バージョンは 1 と 2）
- 想定外のファイル・パス、シンボリックリンク、暗号化されたファイル
- チェックサムやサイズが一致しないファイル、宣言のない素材
- 「素材URL」型の値が `/` で始まるローカルパスのまま（素材を同梱していない）
- 項目定義や値が [コンテンツとコレクション](/docs/resources) のルールに合わない

外部の `http://`・`https://` のURLはそのまま取り込まれます（ファイルはダウンロードされません）。

## 管理APIでの受け渡し

[管理API](/docs/management-api) のトークンで、同じ操作ができます。

| メソッドとパス | 内容 |
|---|---|
| `GET /api/v1/sites/{site}/interchange/export` | 管理用ZIPをダウンロードします。 |
| `POST /api/v1/sites/{site}/interchange/preview` | `package` にZIPファイルを付けて（multipart）送信し、内容を確認します。 |
| `POST /api/v1/sites/{site}/interchange/import` | `token` と `confirm: true` を送信し、取り込みを実行します。 |

```sh
# 書き出し
curl -o site.magichtml.zip \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  'https://cms.magichtml.dev/api/v1/sites/SITE_ID/interchange/export'

# 内容の確認
curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -F 'package=@site.magichtml.zip' \
  'https://cms.magichtml.dev/api/v1/sites/SITE_ID/interchange/preview'
```

確認のレスポンス例：

```json
{
  "data": {
    "token": "（48文字のトークン）",
    "name": "ブランドサイト",
    "resources": [
      {"key": "news", "kind": "collection", "name": "お知らせ", "fields": 2, "records": 12, "skipped": false},
      {"key": "contact", "kind": "form", "name": "お問い合わせ", "fields": 3, "records": 0, "skipped": true}
    ],
    "skipped": ["contact"],
    "assets": 4,
    "expires_in_minutes": 30
  }
}
```

`skipped` は取り込まれないリソース（フォーム）の識別キーです。

```sh
# 取り込みの実行
curl -X POST \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{"token": "TOKEN", "confirm": true}' \
  'https://cms.magichtml.dev/api/v1/sites/SITE_ID/interchange/import'
```

成功すると 201 で、作成されたリソースのIDが返ります。

```json
{"data": {"resource_ids": ["..."]}}
```

識別キーの重複、ZIPの検証エラー、確認トークンの期限切れ・使用済みなどは 422 で返ります。パッケージに関するエラーのメッセージは `errors.package` に入ります。

---

# 管理API

管理APIを使うと、サイト・リソース・データ・素材の作成や更新、公開を、プログラムやスクリプトから行えます。個人用のAPIトークンで認証し、自分が所有するサイトだけを操作できます。静的サイトから公開データを読むだけなら、管理APIではなく [公開API](/docs/public-api) を使ってください。

## APIトークン

### 発行する

1. 管理画面の上部メニューから「アカウント・API」を開きます。
2. 「管理APIトークン」の「名前」に用途（例：開発用クライアント）を入力し、「トークンを発行」を押します。
3. 表示されたトークンをコピーします。**トークンはこの画面で一度だけ表示されます。**

| 項目 | 内容 |
|---|---|
| 有効期間 | 発行から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）](/docs/interchange) をご覧ください。

過去の公開版への切り替え、素材の名前・公開設定の変更、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` は進むので、項目定義を保存する直前に取得し直してください。
- 型と値のルールは [コンテンツとコレクション](/docs/resources) と同じです。フォーム専用の型（`checkboxes`、`file`）は使えません。

### データの保存（`entries`）

- `key`、`values`、`position` はすべて必須です。
- `values` は `{"項目の識別キー": 値}` のオブジェクトです。数値は数値、はい／いいえは `true`／`false`、リンクは文字列または `{"url": "..."}` で送ります。
- コンテンツはデータが常に1件です。`POST` すると既存のデータが更新され、識別キーは `main` になります。
- 保存先は下書きです。公開APIに反映するには `publish` を呼びます。

## 例：お知らせを作って公開する

```sh
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 を返します。