API

CI やプログラムから、ファイルか ZIP を送って公開し、状態を取れます。送ったあとの流れ（検査、配信先との比較、転送）は、画面から置いたときと同じです。

認証

アカウントの画面の「API クライアントとトークン」でトークンを発行し、すべての要求に Authorization: Bearer <トークン> を付けます。トークンは発行したときに一度だけ表示され、このサービスには SHA-256 だけが残ります。トークンでは、発行したアカウントのサイトにだけ公開できます。

応答はすべて JSON です（エラーも）。トークンがない・違う・失効したときは 401、ほかのアカウントのサイトやデプロイは 404 です。
応答には Cache-Control: private, no-store と Vary: Authorization が付きます。
クライアントごとに 1 分あたりの回数の上限があり、超えると 429 と Retry-After を返します。

サイトの一覧

GET /api/v1/sites

{"data": [{"id": "…", "name": "corporate", "public_url": "https://example.jp/", "destination": {"name": "Example server", "provider": "sftp"}}]}

配信先は名前と種類だけを返します。ホスト・ユーザー・認証情報は返しません。

公開する

POST /api/v1/sites/{site}/deployments
Content-Type: multipart/form-data

項目	内容
`file`	必須。1 ファイルか ZIP（100MB まで）
`kind`	`file`（1 ファイルとして置く）か `archive`（ZIP を展開する）。省くと、`.zip` は `archive`、それ以外は `file`
`path`	リモートのパス。`file` はファイルのパス（例：`/docs/brochure.pdf`。省くとルートに同じ名前）、`archive` は展開するフォルダ（省くとルート）
`confirm`	`1` なら、配信先と比べたあと確認を待たずに公開します。省くと `prepared` で止まり、`/confirm` を待ちます

curl -H "Authorization: Bearer $TOKEN" -H "Accept: application/json" \
  -F file=@site.zip -F confirm=1 \
  https://publisher.magichtml.dev/api/v1/sites/$SITE/deployments

受け付けると 202 とデプロイを返します。100MB に近いファイルは、アプリに届く前にサーバーが 413 で断ることがあります。転送は裏で進むので、GET /api/v1/deployments/{id} で状態を見てください。検査に通らないときは 422 で、errors.file に問題をすべて並べます。

デプロイの状態

GET /api/v1/deployments/{deployment}
GET /api/v1/sites/{site}/deployments

{"data": {
  "id": "…", "site_id": "…", "number": 12, "kind": "archive", "path": "/",
  "source": {"name": "site.zip", "size": 1234, "sha256": "…", "kept": true},
  "status": "succeeded", "status_label": "公開済み", "automatic": true,
  "counts": {"added": 3, "updated": 5, "deleted": 1, "unchanged": 40},
  "message": null, "public_url": "https://example.jp/", "rollback_of": null,
  "expires_at": null, "created_at": "…", "finished_at": "…",
  "log": [{"at": "…", "message": "…"}]
}}

`status`	意味
`building`	受け付けた。比べる順番を待っている
`planning`	配信先の今のファイルと比べている
`prepared`	比べ終わった。`/confirm` を待っている（30 分で取り消し）
`queued`・`checking`・`uploading`・`writing`	公開している
`removing`	前の ZIP にあって今回はないファイルを削除している
`pending`	Cloudflare Pages が処理している
`succeeded`	公開した
`unknown`	結果を確かめられない。もう一度は送っていない。管理画面で配信先と照合する
`failed`・`cancelled`	失敗・取り消し。配信先には書き込んでいない（`failed` の理由は `message`）

確認・取り消し

POST /api/v1/deployments/{deployment}/confirm
POST /api/v1/deployments/{deployment}/cancel

confirm は prepared のときだけ、cancel は転送を始める前（building・prepared・queued）だけできます。できないときは 409 です。

Cloudflare Pages

Cloudflare Pages は、デプロイごとにプロジェクト全体を公開します。そのため、ZIP はプロジェクト全体として公開します。1 ファイルを送ると、そのサイトがその配信先に最後に公開したすべてのファイルに、そのファイルを足して（置き換えて）公開します。ほかのファイルは消えません。最初の公開は ZIP で行ってください。