API and MCP docs · ClippingSpace

Overview

Two ways in, one set of rules. The REST API at https://clippingspace.tech/api/v1 speaks JSON over HTTPS. The MCP server at https://clippingspace.tech/api/mcp gives AI assistants the same abilities as tools. Both act as your account, with your plan's source minutes, clip limits and connected accounts, exactly as if you used the app.

A typical run:

Create a project from a video link.
Poll the project until its status is completed.
Download the clips, or edit one with an instruction and render it.
Schedule the result to your connected accounts.

Authentication

API access is included with Creator and Studio. Create a key in Settings, API & MCP and send it in the Authorization header of every request:

Header

Authorization: Bearer cs_live_YOUR_KEY

Keys start with cs_live_ and are shown once, when created. We store only a hash, so a lost key can't be recovered: revoke it and make another. Keys are never accepted in a URL. Your account's email must be verified.

Quick start

Start a project, then check on it with the id you get back.

Create clips

curl -X POST https://clippingspace.tech/api/v1/projects \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.youtube.com/watch?v=VIDEO_ID", "rightsConfirmed": true }'

Response (202)

{
  "project": {
    "id": "cmh1x...",
    "title": "YouTube import",
    "status": "queued",
    "stage": "queued",
    "progress": 0,
    "clipCount": 0,
    ...
  }
}

Endpoints

All paths are relative to https://clippingspace.tech/api/v1. The full schema is in the OpenAPI 3.1 document.

POST/projects

Start clipping a video

Answers 202 with the queued project. rightsConfirmed: true is required: it confirms you own the video or have permission to use it. All options are optional and fall back to your account defaults. clipCount is "auto" or a number up to your plan's cap; clipLength is "auto" or 15, 30, 60, 90 or 180 seconds; language is "auto" or a language code like "en"; section takes seconds; liveLastMinutes clips the end of a live stream. hook burns the AI-written hook line over each clip's first seconds and autoZoom adds short push-ins on emphatic moments; both are on unless you changed your defaults, and false turns them off.

curl

curl -X POST https://clippingspace.tech/api/v1/projects \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "rightsConfirmed": true,
    "options": {
      "aspectRatios": ["9:16"],
      "captionStyle": "hormozi",
      "clipCount": 5,
      "hook": false,
      "section": { "start": 600, "end": 1800 }
    }
  }'

GET/projects

List projects, newest first

Paginated with limit (1 to 100) and cursor, the nextCursor of the previous page. Filter with status: queued, processing, completed, failed or canceled.

curl

curl "https://clippingspace.tech/api/v1/projects?limit=20&status=completed" \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

GET/projects/{id}

Status, progress and clips

status is the coarse state, stage the pipeline step (downloading, transcribing, analyzing, rendering) and progress a percentage. Poll every 20 to 60 seconds; processing takes minutes.

curl

curl https://clippingspace.tech/api/v1/projects/PROJECT_ID \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

GET/clips/{id}

One clip

Times, score, format and render status. hasDraft is true when edits are saved but not rendered.

curl

curl https://clippingspace.tech/api/v1/clips/CLIP_ID \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

GET/clips/{id}/download

Signed download link

Returns { url, expiresAt }. The link needs no key and expires, so fetch a fresh one when you need it. Counts as a download. A clip that is still rendering answers 409.

curl

curl https://clippingspace.tech/api/v1/clips/CLIP_ID/download \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

GET/clips/{id}/captions

Caption file (SRT or WebVTT)

Answers with the file itself: format=srt (the default) or format=vtt. The times match the rendered MP4, cuts, speed ramps and freezes included. Captions switched off in the video are still served, so you can upload them separately. A clip without captions answers 404 (no_captions), one that is still rendering 409.

curl

curl -o clip.srt "https://clippingspace.tech/api/v1/clips/CLIP_ID/captions?format=srt" \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

POST/clips/{id}/edit

Edit with the AI assistant

The editor's assistant, in plain words: trims, caption style, size and position, layout, format, title and caption text. The change is saved to the clip's draft and returned as { reply, steps, draft }. Nothing renders until you call render.

curl

curl -X POST https://clippingspace.tech/api/v1/clips/CLIP_ID/edit \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "Cut it to the best 30 seconds and make the captions bigger" }'

POST/clips/{id}/render

Render the saved draft

Answers 202 when a render was queued. Poll the clip until its status is ready. The body is optional: send effects (zoom punch-in, shake, flash, speed ramp, freeze frame, glitch, vignette, grain) and grade (a colour look) to replace the draft's before rendering. Effect times are source seconds, like startSec and endSec; parameters and their ranges are in the OpenAPI document. Send segments to split and rearrange the clip: a list of { id, start, end } pieces of the source in play order, in source seconds. Pieces never overlap, and startSec/endSec become their span. null plays the plain range again. Send hook (up to 120 characters) to change the hook banner's text, or "" to hide it.

curl

curl -X POST https://clippingspace.tech/api/v1/clips/CLIP_ID/render \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "effects": [{ "id": "hit1", "effect": "zoom_punch", "start": 62.4, "end": 63.4 }], "grade": { "lut": "teal_orange", "strength": 0.8 } }'

POST/schedule

Post or schedule a clip

Send scheduledAt (ISO 8601 with offset) or "now": true. Account ids come from GET /accounts. Posts the platform would reject (caption too long, clip too long) are refused with 422. For YouTube, youtubeVisibility picks public (the default), unlisted or private.

curl

curl -X POST https://clippingspace.tech/api/v1/schedule \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clipId": "CLIP_ID",
    "accountIds": ["ACCOUNT_ID"],
    "caption": "New episode out now",
    "scheduledAt": "2027-01-15T18:00:00Z"
  }'

GET/accounts

Connected social accounts

The accounts you connected in Settings. Tokens are never returned.

curl

curl https://clippingspace.tech/api/v1/accounts \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

GET/usage

Usage and limits

Source minutes used and left this month, your plan's limits and the API rate limits.

curl

curl https://clippingspace.tech/api/v1/usage \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

MCP server

The server speaks Streamable HTTP at https://clippingspace.tech/api/mcp and is stateless, so it works with any client that supports remote MCP servers and custom headers. Its tools:

create_clips: start clipping a video URL you have the rights to use (rightsConfirmed), optionally a section, the end of a live stream, a clip count or a caption style
get_project: status, progress, stage and clips of a project
list_projects: your projects, newest first
list_clips: the clips of one project
get_clip_download_url: a signed, expiring link to a clip's MP4
edit_clip: change a clip in plain words with the AI assistant (saved as a draft)
render_clip: render a clip's saved draft, optionally with video effects, a colour grade or split and rearranged pieces
export_clip: re-render a clip at a chosen resolution and frame rate
list_social_accounts: the accounts clips can be posted to
schedule_clip: post a clip now or at a set time
get_usage: source minutes used and left, plan and rate limits

Then ask in plain words, for example: “Clip the last 30 minutes of my stream on Kick and schedule the best clip to TikTok at 6pm.”

Claude Code

Run once in a terminal.

Claude Code

claude mcp add --transport http clippingspace https://clippingspace.tech/api/mcp \
  --header "Authorization: Bearer cs_live_YOUR_KEY"

Claude Desktop

Settings, Developer, Edit Config, then add to claude_desktop_config.json and restart Claude.

Claude Desktop

{
  "mcpServers": {
    "clippingspace": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://clippingspace.tech/api/mcp",
        "--header",
        "Authorization:${CLIPPINGSPACE_AUTH}"
      ],
      "env": {
        "CLIPPINGSPACE_AUTH": "Bearer cs_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop reaches remote servers that use header keys through the mcp-remote bridge, which needs Node.js installed.

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

Cursor

{
  "mcpServers": {
    "clippingspace": {
      "url": "https://clippingspace.tech/api/mcp",
      "headers": {
        "Authorization": "Bearer cs_live_YOUR_KEY"
      }
    }
  }
}

ChatGPT

Through the OpenAI Responses API, which sends the key as a header.

ChatGPT

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "tools": [{
      "type": "mcp",
      "server_label": "clippingspace",
      "server_url": "https://clippingspace.tech/api/mcp",
      "headers": { "Authorization": "Bearer cs_live_YOUR_KEY" },
      "require_approval": "never"
    }],
    "input": "How many source minutes do I have left this month?"
  }'

Connectors added in the ChatGPT app sign in with OAuth, which this server does not offer yet. Use the Responses API, or an agent framework that can set request headers.

Rate limits

Each key may make 60 requests a minute and 2,000 a day, counted across the REST API and MCP tool calls together. Every response carries:

X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds) for the minute window
X-RateLimit-Limit-Day and X-RateLimit-Remaining-Day for the day

Over the limit, you get 429 with Retry-After. Your plan's own limits still apply on top: imports per hour, jobs running at once, AI edits per minute and per day, and source minutes per month.

Errors

Every error has the same shape, with a stable code to branch on and a message to show a person:

Error body

{
  "error": {
    "code": "quota_exceeded",
    "message": "You've used all 300 source minutes on the Creator plan this month."
  }
}

Error codes
Status	Codes	Meaning
400	invalid_request, invalid_json, invalid_cursor, invalid_range, invalid_url	The body or a parameter is wrong. The message names the field.
401	unauthorized, invalid_api_key	No key, a malformed key, or a revoked one.
402	quota_exceeded	Not enough source minutes left this month.
403	plan_required, email_verification_required, upgrade_required, demo_account, account_suspended, account_cleanup	Your plan or account can't do this: no API on this plan, an unverified email, the shared demo account, or an account that is suspended or being deleted.
404	not_found, no_captions	It doesn't exist, it isn't yours, or the clip has no captions.
409	conflict, concurrency_limit, no_draft	Busy or changed: already rendering, too many jobs, nothing to render.
410	gone	The rendered file or the source has expired.
413	payload_too_large	The request body is over 1 MB.
422	validation_failed, invalid_edit	A platform would reject the post (details.issues lists why), or the assistant's edit can't be saved.
429	rate_limited	Slow down. Wait for Retry-After seconds.
500	internal_error	Something failed on our side. Try again in a moment.
503	worker_unavailable, assistant_unavailable	A processing service is briefly down. Retry shortly.

Overview

A typical run:

Create a project from a video link.
Poll the project until its status is completed.
Download the clips, or edit one with an instruction and render it.
Schedule the result to your connected accounts.

Authentication

API access is included with Creator and Studio. Create a key in Settings, API & MCP and send it in the Authorization header of every request:

Header

Authorization: Bearer cs_live_YOUR_KEY

Quick start

Start a project, then check on it with the id you get back.

Create clips

curl -X POST https://clippingspace.tech/api/v1/projects \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://www.youtube.com/watch?v=VIDEO_ID", "rightsConfirmed": true }'

Response (202)

{
  "project": {
    "id": "cmh1x...",
    "title": "YouTube import",
    "status": "queued",
    "stage": "queued",
    "progress": 0,
    "clipCount": 0,
    ...
  }
}

Endpoints

All paths are relative to https://clippingspace.tech/api/v1. The full schema is in the OpenAPI 3.1 document.

POST/projects

Start clipping a video

curl

curl -X POST https://clippingspace.tech/api/v1/projects \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://www.youtube.com/watch?v=VIDEO_ID",
    "rightsConfirmed": true,
    "options": {
      "aspectRatios": ["9:16"],
      "captionStyle": "hormozi",
      "clipCount": 5,
      "hook": false,
      "section": { "start": 600, "end": 1800 }
    }
  }'

GET/projects

List projects, newest first

Paginated with limit (1 to 100) and cursor, the nextCursor of the previous page. Filter with status: queued, processing, completed, failed or canceled.

curl

curl "https://clippingspace.tech/api/v1/projects?limit=20&status=completed" \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

GET/projects/{id}

Status, progress and clips

status is the coarse state, stage the pipeline step (downloading, transcribing, analyzing, rendering) and progress a percentage. Poll every 20 to 60 seconds; processing takes minutes.

curl

curl https://clippingspace.tech/api/v1/projects/PROJECT_ID \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

GET/clips/{id}

One clip

Times, score, format and render status. hasDraft is true when edits are saved but not rendered.

curl

curl https://clippingspace.tech/api/v1/clips/CLIP_ID \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

GET/clips/{id}/download

Signed download link

Returns { url, expiresAt }. The link needs no key and expires, so fetch a fresh one when you need it. Counts as a download. A clip that is still rendering answers 409.

curl

curl https://clippingspace.tech/api/v1/clips/CLIP_ID/download \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

GET/clips/{id}/captions

Caption file (SRT or WebVTT)

curl

curl -o clip.srt "https://clippingspace.tech/api/v1/clips/CLIP_ID/captions?format=srt" \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

POST/clips/{id}/edit

Edit with the AI assistant

curl

curl -X POST https://clippingspace.tech/api/v1/clips/CLIP_ID/edit \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "instruction": "Cut it to the best 30 seconds and make the captions bigger" }'

POST/clips/{id}/render

Render the saved draft

curl

curl -X POST https://clippingspace.tech/api/v1/clips/CLIP_ID/render \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "effects": [{ "id": "hit1", "effect": "zoom_punch", "start": 62.4, "end": 63.4 }], "grade": { "lut": "teal_orange", "strength": 0.8 } }'

POST/schedule

Post or schedule a clip

curl

curl -X POST https://clippingspace.tech/api/v1/schedule \
  -H "Authorization: Bearer cs_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clipId": "CLIP_ID",
    "accountIds": ["ACCOUNT_ID"],
    "caption": "New episode out now",
    "scheduledAt": "2027-01-15T18:00:00Z"
  }'

GET/accounts

Connected social accounts

The accounts you connected in Settings. Tokens are never returned.

curl

curl https://clippingspace.tech/api/v1/accounts \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

GET/usage

Usage and limits

Source minutes used and left this month, your plan's limits and the API rate limits.

curl

curl https://clippingspace.tech/api/v1/usage \
  -H "Authorization: Bearer cs_live_YOUR_KEY"

MCP server

The server speaks Streamable HTTP at https://clippingspace.tech/api/mcp and is stateless, so it works with any client that supports remote MCP servers and custom headers. Its tools:

create_clips: start clipping a video URL you have the rights to use (rightsConfirmed), optionally a section, the end of a live stream, a clip count or a caption style
get_project: status, progress, stage and clips of a project
list_projects: your projects, newest first
list_clips: the clips of one project
get_clip_download_url: a signed, expiring link to a clip's MP4
edit_clip: change a clip in plain words with the AI assistant (saved as a draft)
render_clip: render a clip's saved draft, optionally with video effects, a colour grade or split and rearranged pieces
export_clip: re-render a clip at a chosen resolution and frame rate
list_social_accounts: the accounts clips can be posted to
schedule_clip: post a clip now or at a set time
get_usage: source minutes used and left, plan and rate limits

Then ask in plain words, for example: “Clip the last 30 minutes of my stream on Kick and schedule the best clip to TikTok at 6pm.”

Claude Code

Run once in a terminal.

Claude Code

claude mcp add --transport http clippingspace https://clippingspace.tech/api/mcp \
  --header "Authorization: Bearer cs_live_YOUR_KEY"

Claude Desktop

Settings, Developer, Edit Config, then add to claude_desktop_config.json and restart Claude.

Claude Desktop

{
  "mcpServers": {
    "clippingspace": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://clippingspace.tech/api/mcp",
        "--header",
        "Authorization:${CLIPPINGSPACE_AUTH}"
      ],
      "env": {
        "CLIPPINGSPACE_AUTH": "Bearer cs_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop reaches remote servers that use header keys through the mcp-remote bridge, which needs Node.js installed.

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project).

Cursor

{
  "mcpServers": {
    "clippingspace": {
      "url": "https://clippingspace.tech/api/mcp",
      "headers": {
        "Authorization": "Bearer cs_live_YOUR_KEY"
      }
    }
  }
}

ChatGPT

Through the OpenAI Responses API, which sends the key as a header.

ChatGPT

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "tools": [{
      "type": "mcp",
      "server_label": "clippingspace",
      "server_url": "https://clippingspace.tech/api/mcp",
      "headers": { "Authorization": "Bearer cs_live_YOUR_KEY" },
      "require_approval": "never"
    }],
    "input": "How many source minutes do I have left this month?"
  }'

Connectors added in the ChatGPT app sign in with OAuth, which this server does not offer yet. Use the Responses API, or an agent framework that can set request headers.

Rate limits

Each key may make 60 requests a minute and 2,000 a day, counted across the REST API and MCP tool calls together. Every response carries:

X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds) for the minute window
X-RateLimit-Limit-Day and X-RateLimit-Remaining-Day for the day

Over the limit, you get 429 with Retry-After. Your plan's own limits still apply on top: imports per hour, jobs running at once, AI edits per minute and per day, and source minutes per month.

Errors

Every error has the same shape, with a stable code to branch on and a message to show a person:

Error body

{
  "error": {
    "code": "quota_exceeded",
    "message": "You've used all 300 source minutes on the Creator plan this month."
  }
}

Error codes
Status	Codes	Meaning
400	invalid_request, invalid_json, invalid_cursor, invalid_range, invalid_url	The body or a parameter is wrong. The message names the field.
401	unauthorized, invalid_api_key	No key, a malformed key, or a revoked one.
402	quota_exceeded	Not enough source minutes left this month.
403	plan_required, email_verification_required, upgrade_required, demo_account, account_suspended, account_cleanup	Your plan or account can't do this: no API on this plan, an unverified email, the shared demo account, or an account that is suspended or being deleted.
404	not_found, no_captions	It doesn't exist, it isn't yours, or the clip has no captions.
409	conflict, concurrency_limit, no_draft	Busy or changed: already rendering, too many jobs, nothing to render.
410	gone	The rendered file or the source has expired.
413	payload_too_large	The request body is over 1 MB.
422	validation_failed, invalid_edit	A platform would reject the post (details.issues lists why), or the assistant's edit can't be saved.
429	rate_limited	Slow down. Wait for Retry-After seconds.
500	internal_error	Something failed on our side. Try again in a moment.
503	worker_unavailable, assistant_unavailable	A processing service is briefly down. Retry shortly.

The ClippingSpace API and MCP server

Overview

Authentication

Quick start

Endpoints

POST/projects

GET/projects

GET/projects/{id}

GET/clips/{id}

GET/clips/{id}/download

GET/clips/{id}/captions

POST/clips/{id}/edit

POST/clips/{id}/render

POST/schedule

GET/accounts

GET/usage

MCP server

Claude Code

Claude Desktop

Cursor

ChatGPT

Rate limits

Errors

The ClippingSpace API and MCP server

Overview

Authentication

Quick start

Endpoints

POST/projects

GET/projects

GET/projects/{id}

GET/clips/{id}

GET/clips/{id}/download

GET/clips/{id}/captions

POST/clips/{id}/edit

POST/clips/{id}/render

POST/schedule

GET/accounts

GET/usage

MCP server

Claude Code

Claude Desktop

Cursor

ChatGPT

Rate limits

Errors