API の使い方

画面でできることは、すべて API でもできます。API は JSON で読み書きし、登録と更新のたびに判定と検査をして、その結果を応答に入れて返します。

認証

1. 「APIトークン」でトークンを発行します。トークンの文字列は、発行したときに一度だけ表示されます。
2. リクエストのたびに、Authorization ヘッダーにトークンを付けます。

curl https://assets.magichtml.dev/api/v2/assets \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json"

• トークンは発行したアカウントのもので、そのアカウントのアセット（持ち主 user:<アカウントの番号>）だけを読み書きできます。
• 事務局が用意するフォント（持ち主 system:magic）は、誰でも読めます。書き込むことはできません。
• 有効期間は 90 日です。失効したトークンや期限の切れたトークンは 401 になります。
• 1 分あたりの回数に上限があり、超えると 429 になります。
• 応答はキャッシュされません（Cache-Control: private, no-store）。

書き込みの約束

• request_key：書き込みには、毎回新しい UUID を付けます。同じ request_key で送り直すと、最初の結果をそのまま返し、二重に登録されません。同じキーで中身を変えると 409 です。
• base_revision：ファイルを変える書き込みには、元にしたリビジョンの番号を付けます。その間にほかの書き込みが入っていると 409 になり、応答に今の番号が入ります。
• ファイル：{"path", "json"}・{"path", "text"}・{"path", "blob"} のどれかで指定します。画像などのバイナリは、先に POST /api/v2/blobs に本文として送り、返ってきた sha256 を blob に入れます。blob は 1 日で消えます。
• スキーマ：{"path", "json", "schema": "magic://schemas/..."} のようにスキーマを付けると、そのスキーマで検査します。

エンドポイント

パスはすべて /api/v2 の下です。

例：画像を登録する

curl https://assets.magichtml.dev/api/v2/assets \
  -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  -F request_key=$(uuidgen | tr A-Z a-z) -F kind=image -F title="春の OGP" -F file=@ogp.png

応答（抜粋）：

{
  "asset": {
    "id": "0b6f…",
    "kind": "image",
    "title": "春の OGP",
    "revision": {
      "number": 1,
      "ref": "0b6f…@1",
      "files": [{"path": "image.png", "media_type": "image/png", "size": 48213, "sha256": "…"}],
      "inspection": {
        "verdict": "passed",
        "media": [{"id": "ogp", "version": 1, "label": "OGP画像", "type": "banner", "basis": "1200×630 px が形式「1200 × 630 px」の寸法"}],
        "checks": [
          {"standard": "names", "contract": "media-contract", "version": "0.2.0", "target": null, "verdict": "passed", "violations": [], "details": {"files": 1}},
          {"standard": "formats", "contract": "asset-manager", "version": null, "target": null, "verdict": "passed", "violations": [], "details": {"files": […]}}
        ],
        "contracts": {"media-contract": "0.2.0", "magic-contract": "0.4.0"},
        "inspected_at": "2026-10-10T09:00:00.000000Z"
      }
    }
  }
}

例：制作物にファイルを足す

# 1. 画像を blob として送る
SHA=$(curl -s https://assets.magichtml.dev/api/v2/blobs -H "Authorization: Bearer $TOKEN" \
  --data-binary @front.png -H "Content-Type: application/octet-stream" | jq -r .sha256)

# 2. リビジョン 1 を元に、canvas/front.png を足す
curl https://assets.magichtml.dev/api/v2/assets/$ID/revisions \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"request_key": "'$(uuidgen | tr A-Z a-z)'", "base_revision": 1, "put": [{"path": "canvas/front.png", "blob": "'$SHA'"}]}'

画像の寸法が媒体の CANVAS と違うと、応答の inspection.verdict は failed になります。checks の canvas に canvas.size の違反が入り、expected と actual で寸法の違いがわかります。

検査の結果（inspection）

一覧（GET /assets）とリビジョンの一覧では、verdict と media だけを返します。規格の中身は判定と検査を見てください。

エラー