規約

このページでは、/api/v1alpha1 のすべての operation に適用される pagination、idempotency、rate limit、version、date-time の規約を説明します。

List envelope と cursor

すべての list response は 1 つの envelope を使います。

{
  "data": [],
  "next_cursor": null,
  "has_more": false
}

limit の既定値は 25 で、最大 100 です。next_cursor は値を変更せず cursor として渡してください。cursor を decode、編集、生成しないでください。不正な cursor は 400 invalid-cursor になります。

curl --fail-with-body --get "$BASE_URL/api/v1alpha1/videos" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  --data-urlencode "limit=100" \
  --data-urlencode "cursor=$NEXT_CURSOR"

Idempotency-Key

state-changing POST operation は任意の Idempotency-Key header を受け付けます。論理的な操作 1 つにつき新しいキーを 1 つ使い、同じ body と path parameter の retry では保持してください。

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/runs" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: run-create-01" \
  -d '{"kind":"workflow","workflow_id":"wf_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"}'

キーは 24 時間保持されます。同じ body の replay は元の response を返します。最初の request が処理中なら 409 idempotency-in-flight、異なる body なら 422 idempotency-payload-mismatch です。POST /search と CSV preview のような pure-read POST operation は、この header を無視し、document もしません。

Webhook create は signing secret を create response でだけ返します。完了後の replay は secret を繰り返さず、409 conflict を返します。

Rate limit

request は 1 時間の sliding window で rate limit されます。

各ワークスペースには、そのワークスペースのすべての Public API Alpha key を合わせて 1 時間あたり 10,000 request の共有 budget があります。個々のキーには、より低い per-key limit を設定できます。per-key limit によって、ワークスペースの共有 budget を超える effective limit にすることはできません。

すべての response には次の header が含まれます。

limit を超えると、API は Retry-After header（待機秒数）付きの 429 を返します。Retry-After が経過するまで待ってから retry してください。

Alpha の安定性

/api/v1alpha1 に互換性の保証はありません。breaking revision は新しい path prefix を使います。旧 alpha リビジョンには 30 日間の廃止（Sunset）期間が設けられ、Deprecation ヘッダー（RFC 9745）および Sunset ヘッダー（RFC 8594）によって response 上で通知される場合があります。現在 v1alpha1 の operation は deprecated ではありません。

Date-time

request と response の body に含まれる日時は、明示的な offset を持つ RFC 3339 UTC string です。例は 2026-08-08T10:15:00.000Z です。Retry-After、Sunset、webhook-timestamp は header 固有の形式を使います。

Identifier と wire name

public resource id は vid_、run_、finding_、rep_、prof_、tpl_、wh_、evt_ のような opaque な prefix 付きです。JSON field、query parameter、path parameter は snake_case です。optional field は schema が明示的に nullable と宣言する場合を除き、省略されます。