Conventions
Pagination, idempotency, rate limits, versioning, and date-time formats.
This page documents the pagination, idempotency, rate-limit, versioning, and date-time rules that apply to every /api/v1alpha1 operation.
List Envelopes And Cursors
Every list response uses one envelope:
{
"data": [],
"next_cursor": null,
"has_more": false
}limit defaults to 25 and accepts up to 100. Pass next_cursor back unchanged as cursor. Do not decode, edit, or construct a cursor. An invalid cursor returns 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 operations accept an optional Idempotency-Key header. Use one new key per logical operation and keep it when retrying the same body and path parameters.
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"}'The key is retained for 24 hours. Replaying the same key with the same body returns the original response. Reusing it while the first request is active returns 409 idempotency-in-flight. Reusing it with a different body returns 422 idempotency-payload-mismatch. Pure-read POST operations, including POST /search and the CSV preview operation, ignore this header and do not document it.
Webhook creation returns its signing secret only in the create response. A completed replay returns 409 conflict instead of repeating the secret.
Rate Limits
Requests are rate limited with a sliding 1-hour window.
Each workspace has a shared budget of 10,000 requests per hour across all of its Public API Alpha keys. An individual key can be configured with a lower per-key limit. A per-key limit can never raise the effective limit above the shared workspace budget.
Every response carries these headers:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Effective request budget for the key. |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | Unix time when the current window resets. |
When you exceed the limit, the API returns 429 with a Retry-After header (seconds to wait). Back off until Retry-After elapses, then retry.
Alpha Stability
/api/v1alpha1 has no compatibility promise. A breaking revision uses a new path prefix. The prior alpha revision receives a 30-day sunset period, and responses may carry Deprecation and Sunset headers. No v1alpha1 operation is currently deprecated.
Date-Times
Request and response date-times use RFC 3339 UTC strings with an explicit offset, for example 2026-08-08T10:15:00.000Z. Header-specific exceptions are Retry-After, Sunset, and webhook-timestamp, which use their documented header formats.
Identifiers And Wire Names
Public resource ids are opaque and prefixed, such as vid_, run_, finding_, rep_, prof_, tpl_, wh_, and evt_. JSON fields, query parameters, and path parameters use snake_case. Optional fields are omitted rather than returned as null, except where the schema explicitly declares a nullable member such as next_cursor.