キャッシュクリアAPI ​

CI、CMS、運用スクリプトなどのプログラムから、LightFile Proxyのキャッシュクリアを依頼し、その結果を確認できます。管理画面のキャッシュ操作と同じ指定ができ、CloudFrontのキャッシュ削除も連携して実行できます。

機械可読な仕様（OpenAPI）は https://manage.lightfile-proxy.net/openapi/cache-clear-api.yaml で公開しています。

使い方の流れ ​

1. マネジメントコンソールの 設定 › APIキー で、キーを発行します。
2. POST でキャッシュクリアを依頼し、返ってきた id を保存します。
3. その id で GET し、status が completed か failed になるまで、15〜30秒おきに確認します。

# 1. 依頼する（202 と id が返る）
curl -X POST https://manage.lightfile-proxy.net/api/v1/clusters/example-1/cache-clear-jobs \
  -H 'Authorization: Bearer lfpk_...' \
  -H 'Idempotency-Key: 6f1c2b0e-3d4a-4c1e-9a55-0b8e2f7d91aa' \
  -H 'Content-Type: application/json' \
  -d '{
    "origin": "https://origin.example.com/",
    "paths": ["/images/campaign/", "/css/"],
    "cloudFront": { "distributionId": "E2ABCDEF123456" }
  }'

# 2. 覚えておいた id で状態を尋ねる
curl https://manage.lightfile-proxy.net/api/v1/clusters/example-1/cache-clear-jobs/api-Xa9k... \
  -H 'Authorization: Bearer lfpk_...'

APIキー ​

APIキーは、いくつかの操作を管理画面を介さずにプログラムから指示するためのキーです。キャッシュクリアAPIも、このキーで使います。

• マネジメントコンソールの 設定 › APIキー で発行します。そのクラスタにアクセスできるユーザーなら、どなたでも発行・失効できます。
• キーは発行した直後の1回しか表示されません。 使う仕組みの設定に保存してください。
• 期限は既定で1年です。30日・90日・180日・1年・無期限から選べます。
• キーごとに、許可する操作を選べます。キャッシュクリアAPIで使うのは「キャッシュクリアの依頼」と「キャッシュクリアの状態の確認」です。状態を見るだけの仕組みには、確認だけを許可したキーを渡してください。
• キーはクラスタに属します。発行した人がクラスタの権限を外れても使え続けるので、使わなくなったキーは失効させてください。
• リクエストには Authorization: Bearer <APIキー> のヘッダーを付けます。

ベースURL ​

https://manage.lightfile-proxy.net/api/v1

{clusterId} には、マネジメントコンソールの左上に表示されるクラスタIDを指定します。

キャッシュクリアを依頼する ​

POST /clusters/{clusterId}/cache-clear-jobs

ヘッダー Idempotency-Key（任意）を付けると、同じキーでの再送は新しいジョブを作らず、最初のジョブを返します。通信が途切れて再送したときに、二重にキャッシュクリアが走るのを防げます。値にはUUIDなどを使い、リクエストごとに変えてください。

• 成功すると 202 Accepted と、作ったジョブを返します。同じ Idempotency-Key での再送なら 200 OK です。
• CloudFrontのキャッシュ削除は、指定したパスの末尾に * を付けた前方一致で依頼します（例: /img/a.jpg → /img/a.jpg*）。CloudFrontのキャッシュが多めに削除されても、次のアクセスで取り直すだけで表示には影響しません。
• CloudFrontと連携するとき、paths は15件までです。 CloudFrontは * を含む削除の依頼を、1ディストリビューションあたり同時に15件までしか受け付けないためです。多いときは共通する親のパス（例: /img/）にまとめてください。
• 同じクラスタで終わっていないキャッシュクリアが5件あると、429 を返します。Retry-After の秒数待ってから再送してください。

状態を確認する ​

GET /clusters/{clusterId}/cache-clear-jobs/{id}

{
  "id": "api-Xa9kQ2mP7vR4tN8wB1cD-0c5e91f2a7b3d4e6f8a9b0c1",
  "status": "invalidating",
  "createdAt": "2026-09-14T05:12:03.120Z",
  "updatedAt": "2026-09-14T05:13:41.002Z",
  "requestedBy": { "type": "apiKey", "apiKeyId": "Xa9kQ2mP7vR4tN8wB1cD", "name": "CI（本番デプロイ後）" },
  "target": {
    "urlPrefixes": ["https://origin.example.com/images/campaign/", "https://origin.example.com/css/"],
    "maxEntries": null
  },
  "proxy": {
    "status": "done",
    "progress": 100,
    "message": "キャッシュを削除しました。",
    "startedAt": "2026-09-14T05:12:09.884Z",
    "result": {
      "files": 1284,
      "fileSize": 83123456,
      "byCacheType": [{ "cacheType": "webp", "files": 1284, "fileSize": 83123456 }],
      "examples": [{ "cacheType": "webp", "url": "https://origin.example.com/images/campaign/a.jpg", "fileSize": 48213 }]
    }
  },
  "cloudFront": {
    "status": "inProgress",
    "distributionId": "E2ABCDEF123456",
    "distributionName": "www.example.com",
    "paths": ["/images/campaign/*", "/css/*"],
    "invalidationId": "I2J0PQX7EXAMPLE",
    "requestedAt": "2026-09-14T05:13:40.551Z",
    "completedAt": null,
    "message": "CloudFrontのキャッシュ削除 I2J0PQX7EXAMPLE をリクエストしました。数分で反映されます。"
  }
}

status（全体の状態） ​

completed か failed になったら、確認をやめてください。

cloudFront.status（CloudFrontの状態） ​

CloudFrontと連携しないジョブでは、cloudFront は null です。

untracked になる主な理由は、CloudFront連携設定で登録したIAMロールに cloudfront:GetInvalidation が許可されていないことです。許可すると、完了まで確認できるようになります。

CloudFrontの完了は、依頼を受けて定期的に確認しているほか、この GET のときにも確認し直します。15〜30秒おきに尋ねれば、完了してからほぼ遅れずに completed を受け取れます。

一覧を見る ​

GET /clusters/{clusterId}/cache-clear-jobs?limit=20&requestedBy=self

• 新しい順に返します。管理画面や簡易サイト運用画面から依頼したキャッシュクリアも含みます。
• requestedBy=self を付けると、そのAPIキーで依頼したものだけに絞ります。
• limit は1〜100（既定20）です。続きがあるときは nextCursor が返るので、次のリクエストの cursor にそのまま指定してください。
• 一覧ではCloudFrontに問い合わせ直さないので、最新の状態を知りたいときは個別に GET してください。

指定できる値を調べる ​

ディストリビューションの一覧は、マネジメントコンソールがCloudFrontから読み込んだものです。一覧に無いときは、管理画面の「キャッシュ操作」でCloudFrontのディストリビューションを選ぶ欄を開き、読み込み直してください。

エラー ​

{ "error": { "code": "paths_outside_origin", "message": "…", "details": ["https://other.example.com/img/"] } }

本文がJSONとして読めないとき（壊れたJSONなど）は、この形ではなくHTMLの 400 Bad Request が返ります。APIが受け取る前の段階で弾かれるためです。