# ClutchReel > Paste a long gaming recording. Get evidence-backed short clips and rendered MP4s. Agent API version: 2026-11-14 Machine-readable manifest (JSON, no auth required): https://www.clutchreel.com/api/agent ClutchReel imports a public video, transcribes and analyzes it in the background, proposes short moments with exact timestamps and evidence, and renders MP4s you download from a short-lived signed URL. It is built for unattended use: every response carries nextActions. ## Authentication Use the account's automation token as a bearer credential: Authorization: Bearer cfa_… Create or rotate the token in ClutchReel: Settings -> Automation & watch folder. The secret is shown once; only its SHA-256 hash is stored. Cookies and query-string tokens are never accepted. All agent endpoints are scoped to the token's account. ## Recommended workflow 1. create_project — Import a public video URL with a prompt and a stable idempotencyKey. This charges source minutes once per unique source. 2. get_project — Poll until status is "ready" (stage "ready_for_review"). Wait nextActions[].afterSeconds between calls. 3. list_clips — Read the suggested moments with their exact ranges and evidence. Evidence is evidence, not a virality prediction. 4. refine_clips — If the moments are wrong, re-prompt. This reuses stored signals and does not re-import or charge source minutes. 5. render_clips — Render up to five clips as vertical MP4s with burned-in captions. 6. get_render — Poll until status is "completed", then download the file from downloadUrl before it expires. ## HTTP API Every success is { data, nextActions, warnings? }. Every failure is { error: { code, message, retryable, details? } }. POST /api/agent/projects — Import a video Start a ClutchReel project from a public video URL. Processing (download, inspect, transcribe, analyze) runs in the background and charges source minutes once. Use when: An agent has a video to clip: a public HTTPS media file, or a YouTube video/Shorts/live link. Set a prompt to describe the moments wanted. Arguments: sourceUrl? (body), uploadId? (body), name? (body), prompt? (body), highlightMode? (body), captionLanguage? (body), targetClipSeconds? (body), targetClipCount? (body), transcript? (body), idempotencyKey? (body) GET /api/agent/projects — List projects List the account's projects, newest first, with status and clip counts. Use when: Discover existing projects before creating a new one, or resume earlier agent work. Arguments: page? (query) GET /api/agent/projects/{projectId} — Get project status Read one project with its stage, measured progress, settings, transcript metadata, error, clips, renders and recent events. Use when: Poll after create_project or retry_project. Honor nextActions[].afterSeconds instead of tight polling. Arguments: projectId (path) GET /api/agent/projects/{projectId}/clips — List clips List every clip for a project with exact source ranges, review state, evidence and caption settings. Use when: Inspect the moments before deciding what to render or re-prompt. Arguments: projectId (path) POST /api/agent/projects/{projectId}/suggestions — Ask for different moments Re-run analysis on the stored signals with a new prompt or settings. It reuses the stored transcript, audio, visual, OCR and chat artifacts, replaces only pending suggestions, and never re-imports the source or charges source minutes. Use when: The existing clips are not what was asked for, or the agent wants moments matching a new description. Arguments: projectId (path), prompt? (body), highlightMode? (body), targetClipSeconds? (body), targetClipCount? (body) POST /api/agent/projects/{projectId}/clips — Create a manual clip Create a clip from explicit timestamps. Use this when suggestions are unavailable or the agent already knows the exact moment. Use when: A prompt produced no usable suggestions and the agent can pick timestamps itself. Arguments: projectId (path), title (body), startSeconds (body), endSeconds (body), captionEnabled? (body) POST /api/agent/projects/{projectId}/renders — Render clips Queue MP4 renders for up to five clips. Each render snapshots the clip revision and settings and runs in the background. Use when: Clips have been reviewed and the agent wants downloadable files. Arguments: projectId (path), clipIds (body), layout? (body), captionsEnabled? (body), captionStyle? (body) GET /api/agent/renders/{renderId} — Get render status Read one render's status and progress. When it is completed, the response includes a short-lived signed download URL (about ten minutes). Use when: Poll after render_clips, then fetch the downloadUrl before it expires. Arguments: renderId (path) POST /api/agent/projects/{projectId}/retry — Retry a failed project Re-queue a failed or canceled project. Retryable failures are safe to retry; permanent failures (unsupported media, quota) are not. Use when: get_project returned status "failed" with error.retryable not false. Do not retry a permanent failure. Arguments: projectId (path) ## MCP The repository ships a stdio MCP server that exposes the same tools with identical arguments: CLIPFORGE_URL=http://localhost:3000 CLIPFORGE_TOKEN=cfa_… bun run mcp Example client configuration: { "mcpServers": { "clipforge": { "command": "bun", "args": ["run", "mcp"], "env": { "CLIPFORGE_URL": "https://www.clutchreel.com", "CLIPFORGE_TOKEN": "cfa_…" } } } } ## Conventions - Times are seconds. Ratios are 0..1. Long jobs report measured progress, not estimates. - Poll a status tool no more often than nextActions[].afterSeconds says (5s for projects). - Send idempotencyKey on create_project; reuse it when retrying so nothing is charged twice. - Re-prompting (refine_clips) reuses stored signals: no re-import and no source-minute charge. - Renders are retained for a limited window; download before the expiry returned by get_render. ## Honest limits - hookScore and confidence are rule-based evidence scores, not virality predictions. - Without an AI provider, suggestions are labelled local heuristics and transcript-based prompt matching is weaker. The manifest's `deployment` field reports what is configured. - No face identity recognition, no continuous tracking, no generative outpainting. - Only public sources: no DRM bypass, no private/age-gated YouTube, no Twitch or Kick pages. - Local files must be uploaded through the resumable automation endpoints (/api/automation/uploads) before create_project can reference the uploadId.