Authentication
Create a Public API Alpha key, select route permissions, and understand workspace access.
Every /api/v1alpha1 request uses an API key in the Authorization header:
curl --fail-with-body "$BASE_URL/api/v1alpha1/videos" \
-H "Authorization: Bearer $DEEPFRAME_API_KEY"Keep the key on a server. Do not put it in browser code, logs, or source control.
Create A Public API Alpha Key
Public API Alpha is the key type that grants access to the DeepFrame API during the alpha. To create one, a workspace admin opens Settings > Developer or Developer keys, selects Public API Alpha, accepts the current API Terms, and selects route permissions. A Standard API key cannot call the alpha surface.
The Public API Alpha is also gated at the workspace level. A platform admin must turn on the workspace alpha opt-in before the API accepts traffic. A valid key in a workspace without opt-in receives 403 forbidden. A key without alpha access receives 404 resource-not-found.
Route Permissions
Select the permissions that match the operations your application uses:
| Permission | Operation family |
|---|---|
READ_VIDEOS | GET /videos, GET /videos/{video_id} |
UPLOAD_VIDEOS | POST /videos, GET /videos/{video_id}/upload, PUT /videos/{video_id}/upload/parts, POST /videos/{video_id}/upload/targets, POST /videos/{video_id}/upload/complete, DELETE /videos/{video_id}/upload |
VIEW_INSIGHTS | GET /runs, GET /runs/{run_id}, GET /runs/{run_id}/answers, GET /findings, GET /findings/{finding_id}, GET /reports, GET /reports/{report_id} |
RUN_WORKFLOWS | POST /runs, POST /runs/{run_id}/cancel, profiles, report templates, and POST /runs/{run_id}/reports |
SEARCH_CONTENT | POST /search |
MANAGE_WEBHOOKS | All /webhooks operations |
MANAGE_RULEBOOKS | All /rulebooks and /workflows operations |
The upload flow requires both UPLOAD_VIDEOS and READ_VIDEOS: the first permission creates and advances the upload session, and the second permission reads video processing status. A full workflow quickstart also needs RUN_WORKFLOWS and VIEW_INSIGHTS.
A valid key without the permission required by an operation receives 403 forbidden. A missing, invalid, expired, inactive, or unbound key receives 401 unauthorized.
Workspace Identity Comes From The Key
The API derives workspace identity from the key. Do not add tenant_id, organization_id, or user_id to a request. A resource in another workspace is intentionally indistinguishable from a missing resource and returns 404 resource-not-found.
Key Safety
- Store the key in a secret manager or an environment variable.
- Send it only from a trusted server.
- Never print or log the key.
- Rotate or deactivate it from Developer settings.
export DEEPFRAME_API_KEY="df_live_..."See Errors for the problem body and Policies for alpha stability and retention rules.