API & webhooks

Available on the API plan. Generate and manage keys from Settings.

Authentication

Send your key as a bearer token on every request. Keys are shown once at creation — store them somewhere safe.

Authorization: Bearer cf_live_...

Endpoints

POST /api/v1/videos

Queue a new clip. Same config shape as the dashboard.

curl -X POST https://clipsforge.pages.dev/api/v1/videos \
  -H "Authorization: Bearer cf_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "sourceType": "youtube_url",
    "sourceRef": "https://youtu.be/...",
    "autoDetect": true,
    "config": { "captions": true, "aspectRatio": "9:16" }
  }'

# -> 201 { "video": { "id", "status", "source_type", "source_ref",
#                      "duration_seconds", "error", "created_at",
#                      "download_url", "download_expires_at" } }
# download_expires_at is set when the video is a storage.to download link
# (free plans, or a paid video over 40 MB sent at full quality); null when
# download_url is a short-lived link to a video kept in your library.

GET /api/v1/videos

List your videos, newest first. ?limit= (default 20, max 100).

GET /api/v1/videos/:id

Poll a single job’s status and download link.

curl https://clipsforge.pages.dev/api/v1/videos/<id> \
  -H "Authorization: Bearer cf_live_..."

GET /api/v1/me

Verify a key and read the account’s tier, limits and current usage.

Rate limits

120 read requests / minute, per key.
10 write requests / minute, per key (video creation).

A 429 response includes standard X-RateLimit-* headers.

Discord webhooks

Set a webhook URL in Settings and we’ll POST a message to it every time one of your clips finishes rendering — whether it was queued from the dashboard or the API.