Back to home

ClipForge API

Build integrations on top of ClipForge. Upload videos, manage clips, and track processing jobs programmatically.

Base URL

https://api.clipforge.app

Local development uses http://localhost:8000.

Authentication

Authenticated endpoints require a Clerk session token in the Authorization header:

Authorization: Bearer <clerk-session-token>

Use the getToken() helper from @clerk/nextjs on the client, or a valid Clerk JWT from your backend.

Videos

Upload long-form videos, list them, manage captions, and trigger processing.

POST/api/v1/videos/presigned-upload?filename={name}AUTH

Get a presigned URL to upload the source video directly to object storage.

POST/api/v1/videosAUTH

Register a new video after the file has been uploaded to storage.

Body: { title, source_key, source_language, target_language, subtitle_*, audio_mode, voice }
GET/api/v1/videosAUTH

List all videos for the authenticated user.

POST/api/v1/videos/{video_id}/completeAUTH

Mark the upload as complete and queue the split/processing job.

GET/api/v1/videos/{video_id}/clipsAUTH

List clips generated for a specific video.

GET/api/v1/videos/{video_id}/transcriptAUTH

Get the transcript/captions for a video.

PUT/api/v1/videos/{video_id}/transcriptAUTH

Update the transcript/captions for a video.

Body: { segments: [{ start, end, text }] }
DELETE/api/v1/videos/{video_id}AUTH

Delete a video and all its clips from storage and the database.

Clips

Manage generated vertical clips: download, edit timing, regenerate, or delete.

GET/api/v1/clips/{clip_id}/downloadAUTH

Get a temporary presigned download URL for a finished clip.

PATCH/api/v1/clips/{clip_id}AUTH

Update a clip's start/end time and caption style.

Body: { start_time, end_time, subtitle_* }
POST/api/v1/clips/{clip_id}/regenerateAUTH

Re-process a clip with updated timing or caption settings.

DELETE/api/v1/clips/{clip_id}AUTH

Delete a single clip from storage and the database.

Jobs

Track the status and progress of background processing jobs.

GET/api/v1/jobs/{job_id}AUTH

Get the current status, progress, and error message for a job.

Users

Access the current user's profile and activity feed.

GET/api/v1/users/meAUTH

Get the current authenticated user.

GET/api/v1/users/me/activity?limit=20AUTH

Get a combined feed of recent uploads and job updates.

Public

Unauthenticated endpoints for demos and public clip sharing.

GET/api/v1/public/demo-clips?limit=3

Return a small set of finished clips for landing-page demos.

GET/api/v1/public/clips/{clip_id}

Return a single finished clip for public sharing pages.

POST/api/v1/waitlist

Join the waitlist with an email address.

Body: { email, source? }

Billing

Subscription portal and Paddle webhook handling.

POST/api/v1/billing/portalAUTH

Create a Paddle customer portal session for self-service billing.

GET/api/v1/billing/subscriptionAUTH

Get the current user's active subscription details.

POST/api/v1/billing/webhook

Receive Paddle webhook events (subscription lifecycle, customer updates).

Response format

Successful responses return JSON with the requested resource. Errors use standard HTTP status codes:

  • 400 — Bad request (invalid payload or parameters)
  • 401 — Unauthorized (missing or invalid token)
  • 404 — Resource not found
  • 500 — Internal server error