HTTP API リファレンス

CLI / MCP / GitHub Action を使わず、HTTP で直接 Miseru を操作するためのリファレンスです。ベース URL は https://api.miseru.dev です。

認証

公開 API はすべて Upload Token で認証します。

Authorization: Bearer msr_••••••••

• トークン形式は msr_ + 64桁の16進文字列(256bit)です
• トークンはダッシュボードのプロジェクト単位で発行します(平文が見られるのは発行時の一度きり。サーバーには SHA-256 ハッシュのみ保存されます)
• 1つのトークンでアップロード・失効・コメント取得のすべてを行えます
• 失効(revoke)済みトークンは即座に使えなくなります

認証に失敗した場合はすべて 401 { "error": "unauthorized" } を返します。

---

POST /v1/upload

画像をアップロードし、署名付き配信 URL と PR 貼り付け用 markdown を返します。

リクエスト

multipart/form-data で送信します。

フィールド	必須	型・制約
image	✅	画像ファイル。5MB 未満、image/png / image/jpeg / image/webp のみ
name	✅	スクリーンショット名。1〜200文字
pr_number	✅	対象 PR 番号。正の整数
commit_sha	✅	コミット SHA。16進 7〜40 桁
viewport	—	ビューポートサイズ。幅x高さ 形式(例: 1280x800)

curl -X POST https://api.miseru.dev/v1/upload \
  -H "Authorization: Bearer $MISERU_TOKEN" \
  -F "image=@./shot.png" \
  -F "name=home" \
  -F "pr_number=482" \
  -F "commit_sha=$(git rev-parse HEAD)" \
  -F "viewport=1280x800"

レスポンス(200)

{
  "id": "3f2a…(32桁hex)",
  "view_url": "https://img.miseru.dev/i/<id>.png?exp=<unixtime>&token=<kid>.<hmac>",
  "markdown": "![home](https://img.miseru.dev/i/<id>.png?exp=…&token=…)"
}

• view_url の署名有効期限(exp)はアップロードから365日です。実際の公開停止は失効ポリシーによる削除で行われるため、URL の exp より先にポリシーが優先されます(→ 配信とセキュリティの仕組み)
• markdown をそのまま PR コメントに貼れば画像が表示されます

エラー

ステータス	ボディ	条件
400	{ "error": "invalid multipart/form-data body" }	multipart として解釈できない
400	{ "error": "image file required" }	image フィールド欠落
400	{ "error": "name required" }	name が欠落・空・200文字超
400	{ "error": "pr_number required" }	pr_number が正の整数でない
400	{ "error": "commit_sha required" }	commit_sha が 16進 7〜40 桁でない
400	{ "error": "viewport must be like 1280x800" }	viewport の形式不正
401	{ "error": "unauthorized" }	トークン無効・欠落
413	{ "error": "payload too large (max 5MB)" }	画像が 5MB 以上
415	{ "error": "unsupported content-type (png/jpeg/webp)" }	対応外の画像形式
415	{ "error": "declared <content-type>, but the file content is not a valid <PNG|JPEG|WEBP>" }	宣言した Content-Type とファイルの中身（先頭バイト）が一致しない。文言は宣言された型によって変わる
429	{ "error": "rate limited" } + Retry-After: 60	レート制限超過(プロジェクトあたり 120回/分)

レート制限のカウンタ基盤に障害が起きた場合、アップロードは拒否されません(fail-open)。

---

DELETE /v1/images/:id

画像を1件、即座に失効させます。失効ポリシーに関わらず、いつでも手動失効できます。

curl -X DELETE https://api.miseru.dev/v1/images/<id> \
  -H "Authorization: Bearer $MISERU_TOKEN"

• 失効は「オリジン(R2)削除 → 記録削除」の順で実行されます(キャッシュ済みの配信は Cache-Control による自然失効)
• トークンのプロジェクトに属さない画像 ID は、存在有無を漏らさないため一律 404 を返します

レスポンス

ステータス	ボディ	条件
200	{ "ok": true, "id": "<id>" }	失効完了
401	{ "error": "unauthorized" }	トークン無効
404	{ "error": "not found" }	画像が存在しない(または別プロジェクト)
503	{ "error": "expire failed, retry later" }	失効処理が完了しなかった(後述の自動リトライ対象)

503 の場合でも画像は失効予約済みとしてマークされ、毎時の自動スイープが失効を完了させます。

---

GET /v1/comment

PR の全スクリーンショットを集約した、1 PR = 1 コメント用の markdown を返します。GitHub Action がコメントの投稿・更新に使う API ですが、独自のコメント連携を組む場合にも利用できます。

curl "https://api.miseru.dev/v1/comment?pr_number=482" \
  -H "Authorization: Bearer $MISERU_TOKEN"

レスポンス(200)

{ "pr_number": 482, "markdown": "<!-- miseru:pr-482 -->\n### 📸 スクリーンショット(3枚)\n…" }

• 先頭の HTML コメント <!-- miseru:pr-<n> --> はマーカーです。既存コメントをこのマーカーで探して更新することで「1 PR = 1 コメント」を保ちます
• 画像は投稿順に並び、各エントリに名前・viewport・コミット SHA(7桁)が付きます
• pr_number が正の整数でない場合は 400 { "error": "pr_number required" }

POST /v1/expire

PR クローズ時の失効ポリシーを適用します。通常は GitHub Action が pull_request: [closed] を契機に呼び出します。

curl -X POST https://api.miseru.dev/v1/expire \
  -H "Authorization: Bearer $MISERU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "pr_number": 482 }'

レスポンス(200)

{ "pr_number": 482, "policy": "pr_close", "marked": 3, "expired": 3 }

フィールド	意味
policy	プロジェクトの失効ポリシー
marked	PR クローズ済みとしてマークした画像数
expired	実際に失効(削除)した画像数。pr_close ポリシー以外では常に 0

ポリシーごとの挙動の違いは失効ポリシーの選び方を参照してください。

---

ダッシュボード API について

https://app.miseru.dev のダッシュボードは、セッション Cookie 認証の /v1/dashboard/* API(プロジェクト管理・トークン発行・画像一覧など)を使っています。これは Web ダッシュボード専用の内部 API であり、安定した公開契約ではありません。予告なく変更されることがあるため、自動化には上記の Upload Token 認証 API を使ってください。