Clip or Die API

Everything the web app does is an API call. The same engine is exposed three ways: REST under /v1, an MCP server at /mcp, and the web app itself (which is just a client of the API).

Quick start

1. Create a key in the app under API & agents (scopes: read, clip, post, admin).
2. Add a watched source. Clips from new uploads land automatically.
3. List clips by score and download the winners. (Approving and auto-posting are internal beta; see Posts.)

curl -X POST https://api.clipordie.com/v1/sources \
  -H "Authorization: Bearer cod_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "youtube_channel",
    "url": "https://youtube.com/@MrBallen",
    "rights": "licensed",
    "license_ref": "campaign-2026-10",
    "watch": true,
    "backfill": 3,
    "ruleset_text": "Horror stories only. Skip sponsor reads. 30-60s. End on the reveal.",
    "clip_prefs": { "lengths": [30, 60], "max_clips": 10 }
  }'

Authentication

Send one of:

• Authorization: Bearer cod_live_… — a workspace API key. Keys carry scopes; post is required for anything that publishes, admin for keys and billing.
• x-api-key: cod_live_… — same thing, for MCP clients that only set custom headers.
• Authorization: Bearer <Cognito access token> — what the web app sends. Sessions have all scopes. Add ?ws=ws_… to pick a workspace other than your default.

Keys look like cod_live_ + 32 characters. We store only a SHA-256 hash, so the full key is shown exactly once at creation.

Conventions

• Lists return {"items": [...], "next": "cursor" | null}. Pass cursor= to page.
• Errors return {"error": {"code": "...", "message": "..."}} with a 4xx/5xx status.
• Idempotency: send Idempotency-Key: <uuid> on any POST; the same key within 24 hours replays the original response.
• Identifiers: ws_ workspace · src_ source · job_ job · clp_ clip · kit_ brand kit · acc_ account · sch_ schedule · pst_ post · key_ API key.
• Media: every video/thumbnail URL is a presigned link valid for 15 minutes. Fetch the object again for a fresh one.

Plans & limits

Usage counts source minutes once per job (at ingest) and clips once per rendered clip (usage.clips vs limits.clips). Re-renders and caption edits are free. A limit hit returns 402 plan_limit. GET /v1/usage shows the period's counters against your limits, plus features: {posting, download}.

Workspace & keys

The signed-in user and their workspaces: {user, workspaces: [{ws_id, name, plan, role}]}.

Workspace metadata, usage, limits, features: {posting, download}, mcp_url and (internal) the posting-rail profile up_profile.

Body: {name?, owner_phone?}

Body: {name, scopes: ["read","clip","post","admin"]} → {key_id, key, prefix, scopes}. key is only ever returned here.

{ "key_id": "key_7f2a91c0", "key": "cod_live_Qm3…k9Z", "prefix": "cod_live_Qm3a…k9Z",
  "scopes": ["read","clip","post"] }

Sources

A source is a watched subscription: a channel, playlist, feed, VOD, folder, upload or single URL. It carries rules, a brand kit, a gate and (optionally) a posting schedule.

Body: {type, url, rights, license_ref?, watch?, backfill?, ruleset_text?, brandkit_id?, gate?, clip_prefs?, schedule?} → source (+ job_ids when backfill > 0 or it's a single item).

• type: youtube_channel | youtube_video | youtube_playlist | rss | twitch_vod | kick_vod | drive | upload | url
• rights: owned | licensed | campaign | unknown. Nothing ever posts from an unknown source; its clips are banked only until you change it.
• gate: {auto_post_min_score: 80, approval_channel: "app"|"imessage"|"email"|"none", originality_min: 0.5, hold_all: false} Internal beta; public clips land ready.
• clip_prefs: {lengths: [30,60], max_clips: 10, formats: ["9:16"]}
• schedule: {account_ids, per_day, windows: [["09:00","10:00"],…], tz} creates and links a schedule in one call. Internal beta.

Any mutable field. {"watch": false} pauses the watcher.

Removes the source. Its clips stay in the bank.

Body: {limit?: 1} → clip the newest N items now → {job_ids}.

{ "id": "src_4c1e9a0b77d2", "type": "youtube_channel", "url": "https://youtube.com/@MrBallen",
  "title": "MrBallen", "rights": "licensed", "watch": true, "backfill": 3,
  "ruleset_text": "Horror stories only…", "brandkit_id": "kit_…", "schedule_ids": ["sch_…"],
  "gate": {"auto_post_min_score": 80, "approval_channel": "app", "originality_min": 0.5, "hold_all": false},
  "clip_prefs": {"lengths": [30,60], "max_clips": 10, "formats": ["9:16"]},
  "status": "active", "last_checked": "2026-10-06T14:03:00Z", "created": "2026-10-06T13:00:00Z",
  "job_ids": ["job_…","job_…","job_…"] }

Jobs & uploads

Body: {filename, content_type} → {upload_key, put_url}. PUT the file to put_url (valid 1 hour), then start a job with upload_key.

Body: one of {url} · {upload_key} · {source_id}, plus {ruleset_text?, brandkit_id?, max_clips?, lengths?, formats?, rights?} → job (status: "queued"). URL jobs auto-create a hidden source so every clip has one.

A job carries status, progress (0–100), stage_msg, clips_count, source_minutes, error, and clips ids when done. Poll every few seconds while it runs.

{ "id": "job_8f31a0c2e4d9", "kind": "clip", "status": "rendering", "progress": 72,
  "stage_msg": "Rendering clip 7 of 10", "src_id": "src_…", "input": {"url": "https://…"},
  "clips_count": 6, "source_minutes": 48.2, "created": "…", "updated": "…" }

Clips

Filters: source_id, job_id, status, min_score, since, limit, cursor. Statuses: ready | needs_approval | approved | scheduled | posted | skipped | held | failed.

The clip plus urls: {video, thumb} (presigned, 15 min).

Body: {title?, caption?, hashtags?, hooks?}. Free; never costs usage.

Body: {account_ids?}. Schedules the clip into the next free slot of each account (or the source's own schedule when omitted) → {post_ids}. Refused for rights: unknown sources and unhealthy accounts. Internal beta: public plans get 403 posting_not_available.

Body: {brandkit_id?, hook?, caption_style?, length?, format?, start?, end?} → a job with kind: "rerender". Free.

→ {url} presigned 1080x1920 MP4 (15 min). This is the Phase 1 output for every plan; no watermark.

{ "id": "clp_2d7b4e9a10f3", "job_id": "job_…", "src_id": "src_…",
  "source_title": "Man finds a door in his basement", "source_url": "https://…",
  "title": "The door in the basement wasn't there yesterday",
  "hooks": [{"text": "He opened the door and it wasn't empty", "score": 96}, …],
  "start": 1412.4, "end": 1453.9, "duration": 41.5,
  "score": {"total": 94, "hook": 96, "flow": 91, "payoff": 95, "trend": 88,
            "why": "Cold open on the discovery, complete arc, ends on the reveal."},
  "transcript": "…", "status": "needs_approval",
  "renders": {"default": {"key": "ws/…/default.mp4", "w": 1080, "h": 1920, "bytes": 8123456, "kit_id": "kit_…", "hook": "…"}},
  "caption": "He opened the door…", "hashtags": ["#horror","#truestory"], "credit_line": "Full story: @MrBallen",
  "originality": 0.71, "posts": [], "urls": {"video": "https://…", "thumb": "https://…"},
  "created": "…", "updated": "…" }

Brand kits

Fields: name, font, colors {primary, accent, text}, caption_style (wordpop|karaoke|static), highlight_color, caption_pos (0–1), emojis, logo_pos, endplate_seconds, cta, hook_style, banned_words[], required_lines[], credit_template, is_default.

Body: {kind: "logo"|"endplate", filename} → {put_url}. PUT the PNG there.

AccountsInternal beta — coming soon for all plans

Connected social accounts. Posting runs through our rail; each account keeps its own cadence and health.

Phase 1: these routes answer 403 posting_not_available for free, creator, clipper and agency workspaces. They are live for internal workspaces and will open to all plans soon. Check features.posting on GET /v1/workspace.

Body: {platforms: ["tiktok","instagram","youtube","facebook","x","linkedin","threads","pinterest"]} → {url}. Open it in a browser, sign in to each platform, then sync.

Pulls the connected accounts from the rail and upserts them → list.

Body: {per_day, windows, tz, jitter_min, angle: {kit_id?, hook_style?}, health: "paused"}.

{ "id": "acc_91b3c0d7e2a5", "platform": "tiktok", "handle": "@horrorbeathq", "display": "HorrorBeat",
  "rail": "upload_post", "health": "healthy", "per_day": 3,
  "windows": [["09:00","10:00"],["13:00","14:00"],["18:00","19:00"]], "tz": "America/Chicago",
  "jitter_min": 20, "angle": {"kit_id": "kit_…", "hook_style": "question"},
  "warmup_stage": 3, "last_post_at": "…", "created": "…" }

SchedulesInternal beta — coming soon for all plans

Fields: name, account_ids[], source_ids[] (empty = all), per_day, windows, tz, jitter_min, paused_until?.

Slot picking walks forward from now through each account's windows (in the account's timezone), one post per window up to per_day, skipping taken slots, with ± jitter_min.

PostsInternal beta — coming soon for all plans

Body: {clip_id, account_ids, at?: iso | "next" | "now"} → POST items with status: "scheduled". Omit at for the next free slot per account.

Filters: status (scheduled|posting|sent|failed|canceled), clip_id, account_id.

Every sent post carries a receipt: platform_url, platform_id, sent_at, rail_request_id. Failures retry up to 3 times (2m / 10m / 30m) and then stay failed with the error, never silently.

Metrics & analyticsInternal beta — coming soon for all plans

Query: clip_id | account_id | source_id and window=1h|24h|72h|7d → views, likes, comments, shares.

→ {posted_7d, views_7d, best_hooks[], best_slots[], usable_ratio, calibration}. Sparse early on; fills in as posts age.

Period usage against plan limits.

Last 100 workspace events (jobs, posts, approvals, billing, agent actions).

Billing

Body: {plan: "creator"|"clipper"|"agency"} → {url} Stripe Checkout. Requires admin.

→ {url} Stripe customer portal (change plan, cancel, invoices).

MCP server

Clip or Die speaks MCP Streamable HTTP at POST https://api.clipordie.com/mcp (JSON-RPC 2.0; one JSON object per response, no SSE needed). Authenticate with your API key as a Bearer token or x-api-key. Protocol version 2025-06-18.

Claude Code

claude mcp add --transport http clipordie https://api.clipordie.com/mcp \
  --header "Authorization: Bearer cod_live_…"

Generic config (Claude Desktop, Cursor, Windsurf, …)

{
  "mcpServers": {
    "clipordie": {
      "type": "http",
      "url": "https://api.clipordie.com/mcp",
      "headers": { "Authorization": "Bearer cod_live_…" }
    }
  }
}

Then say: "Start clipping youtube.com/@MrBallen, horror stories only, 30 to 60 seconds, and download anything over 80." The agent will call add_source, poll list_clips and hand you the download links.

MCP tools

Each tool is a thin wrapper over the same functions the REST routes use. Results come back as a JSON string in content[0].text. Tools marked internal beta return isError: true with posting_not_available on public plans until auto-posting opens to all.

Raw JSON-RPC example

curl -X POST https://api.clipordie.com/mcp \
  -H "Authorization: Bearer cod_live_…" -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"list_clips","arguments":{"status":"needs_approval","min_score":70}}}'

Object shapes

Errors

State machines

JOB:  queued → claimed → ingesting → transcribing → selecting → rendering → done | failed | canceled
POST: scheduled → posting → sent | failed  (retry ≤3: 2m / 10m / 30m) | canceled
CLIP: ready → (gate) → needs_approval | scheduled → posted
      approve → scheduled · skip → skipped · hold → held

Public plans (Phase 1): every rendered clip lands ready; download it from GET /v1/clips/{id}/download. Internal gate after render: hold_all → needs_approval. Else if the source has a schedule and score.total ≥ auto_post_min_score and rights ≠ unknown and originality ≥ originality_min → scheduled. Else → needs_approval.