Cutship
Sign inGet started

Docs

MCP + REST API

Your brand, pullable by any AI. Agents and pipelines pull your brand kits and Cutship's editing assets as code plus structured specs, over MCP or plain HTTP, from one key.

Three steps: create a key, connect your agent, ask it to pull.

Then ask: “Pull my default brand kit from Cutship and add Word Pop captions to this Remotion project.”

Get a key

Create keys in Dashboard → API keys. Keys look like ck_…, are shown once, and can be revoked any time. Give each agent or pipeline its own key so usage is easy to read. Older CLI tokens (cs_…) keep working with pull scope.

ScopeCan
readSearch, list brand kits, get specs and prompts without code, usage, reverse inspo.
pullEverything in read, plus code, generate_variations and log_render.
adminEverything in pull, plus managing keys through the API.

Connect

The hosted MCP server needs no install: https://cutship.ai/api/mcp speaks MCP Streamable HTTP (JSON-RPC 2.0) with the same Authorization header as the REST API. Prefer a local process? npx -y cutship mcp runs the same tools over stdio.

Claude Code

hosted
claude mcp add --transport http cutship https://cutship.ai/api/mcp --header "Authorization: Bearer ck_…"
local stdio
claude mcp add cutship --env CUTSHIP_API_KEY=ck_… -- npx -y cutship mcp

Codex

Add one of these to ~/.codex/config.toml. Codex connects to streamable HTTP servers directly; on older Codex versions use the mcp-remote bridge or the stdio server.

config.toml · hosted
# ~/.codex/config.toml — hosted (streamable HTTP)
[mcp_servers.cutship]
url = "https://cutship.ai/api/mcp"
bearer_token_env_var = "CUTSHIP_API_KEY"   # export CUTSHIP_API_KEY=ck_…
config.toml · mcp-remote
# ~/.codex/config.toml — hosted, through the mcp-remote bridge
[mcp_servers.cutship]
command = "npx"
args = ["-y", "mcp-remote", "https://cutship.ai/api/mcp", "--header", "Authorization: Bearer ${CUTSHIP_API_KEY}"]
env = { CUTSHIP_API_KEY = "ck_…" }
config.toml · stdio
# ~/.codex/config.toml — local stdio server
[mcp_servers.cutship]
command = "npx"
args = ["-y", "cutship", "mcp"]
env = { CUTSHIP_API_KEY = "ck_…" }

Cursor, Claude Desktop and other MCP clients

.cursor/mcp.json, claude_desktop_config.json and most clients take the same mcpServers shape. Local stdio:

mcp.json · stdio
{
  "mcpServers": {
    "cutship": {
      "command": "npx",
      "args": [
        "-y",
        "cutship",
        "mcp"
      ],
      "env": {
        "CUTSHIP_API_KEY": "ck_…"
      }
    }
  }
}

Hosted, for clients that accept a URL (Cursor, Windsurf, VS Code):

mcp.json · hosted
{
  "mcpServers": {
    "cutship": {
      "url": "https://cutship.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer ck_…"
      }
    }
  }
}

Claude Desktop’s config file only launches local commands, so reach the hosted server through mcp-remote:

claude_desktop_config.json · hosted
{
  "mcpServers": {
    "cutship": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://cutship.ai/api/mcp",
        "--header",
        "Authorization: Bearer ${CUTSHIP_API_KEY}"
      ],
      "env": {
        "CUTSHIP_API_KEY": "ck_…"
      }
    }
  }
}

The stdio server reads the key from CUTSHIP_API_KEY, then from npx cutship login ck_… (saved to ~/.config/cutship/config.json). CUTSHIP_TOKEN with a cs_ token still works. npx cutship keys prints where to create keys and which one is in use.

REST basics

Every MCP tool is a REST endpoint under https://cutship.ai/api/v1. Send the key as a Bearer token and JSON bodies with Content-Type: application/json. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining. Asset ids and slugs are interchangeable in paths.

MCP toolRESTScopeCounts as a pull
search_assetsGET /assetsreadNo
get_assetGET /assets/{asset_id}read (spec only) · pull (with code)Yes, once per version per key
get_assets_batchPOST /assets/batchread (spec only) · pull (with code)Yes, per returned asset
list_brand_kitsGET /brand-kitsreadNo
get_brand_kitGET /brand-kits/{kit_id}readNo
get_boardGET /boards/{board_id}read (spec only) · pull (with code) · Pro and upYes, per asset with code
get_packGET /packs/{pack_id}read (spec only) · pull (with code)Yes, per asset with code
generate_variationsPOST /assets/{asset_id}/variationspullNo
reverse_inspoPOST /reverse-insporead · Pro and upNo
get_build_briefPOST /build-briefread · Pro and upNo
save_assetPOST /assetspull · writes to your accountNo
list_boardsGET /boardsreadNo
create_boardPOST /boardspull · writes to your accountNo
add_to_boardPOST /boards/{board_id}/itemspull · writes to your accountNo
save_brand_kitPOST /brand-kitspull · writes to your accountNo
get_taste_profilePOST /tasteread · Pro and upNo
source_mediaPOST /sourceread · Pro and upNo
log_renderPOST /renderspullNo (counts a render)
get_usageGET /usagereadNo
get_clip_kitGET /clip-kitread (spec only) · pull (with code)Yes, per asset with code

You can also call the hosted MCP endpoint directly, without an MCP client:

raw JSON-RPC
curl -X POST https://cutship.ai/api/mcp \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_assets","arguments":{"query":"captions","limit":3}}}'

Tools

Assets come back with code (files + dependencies), spec (params with defaults, timing, fonts, colors, reference frames), an agent prompt, and, when you pass brand_kit_id, the brand_kit they were merged with. Search results leave out code, spec and prompt.

search_assets

read

Search Cutship's approved editing assets (Remotion components, captions, hooks, transitions, carousels, posters, style packs). Filter by free text, format, vibe and access tier, or pass a reference video URL to rank assets that match its look (Pro). Returns asset summaries without code, spec or prompt; call get_asset for those.

InputTypeRequiredDescription
querystringnoFree text, e.g. "word pop captions" or "chrome logo".
reference_urlstringnoA TikTok/Reels/YouTube URL whose style to match (Pro and up).
formatstringnoWhat the asset is made for. One of: captions, hook_overlay, progress_bar, speaker_label, reframe, stinger, story, thumbnail, hook_card, carousel, poster, transition, filter, effect, flow, style_pack, brand_kit_template.
vibestringnoA mood or aesthetic, e.g. "y2k chrome", "soft studio", "bold".
tier"free" | "pro" | "paid"noOnly assets with this access level.
limitinteger (1–100)noDefault 20.
MCP input
{
  "query": "captions",
  "format": "captions",
  "tier": "free",
  "limit": 3
}
REST
curl "https://cutship.ai/api/v1/assets?query=captions&format=captions&tier=free&limit=3" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY"
Output
{
  "assets": [
    {
      "id": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a64",
      "slug": "focus-word-scroll",
      "title": "Focus Word Scroll",
      "type": "component",
      "format": "captions",
      "preview_url": "https://cutship.ai/a/focus-word-scroll",
      "access": "free",
      "price_cents": 0,
      "creator": "cutship",
      "version": "9c41e07ab2d35f18"
    },
    {
      "id": "b7d04a19-2e5c-4c8b-a3f6-58e1d92c0b37",
      "slug": "crt-chroma-credits",
      "title": "CRT Chroma Credits",
      "type": "component",
      "format": "captions",
      "preview_url": "https://cutship.ai/a/crt-chroma-credits",
      "access": "free",
      "price_cents": 0,
      "creator": "cutship",
      "version": "41fa6c0d8e27b953"
    },
    {
      "id": "e85c3f72-91ab-4d06-8c4e-0f2b7a6d1c98",
      "slug": "karaoke-box-captions",
      "title": "Karaoke Box Captions",
      "type": "component",
      "format": "captions",
      "preview_url": "https://cutship.ai/a/karaoke-box-captions",
      "access": "free",
      "price_cents": 0,
      "creator": "cutship",
      "version": "07bd2e95c1a4f368"
    }
  ]
}

get_asset

read (spec only) · pull (with code)

Get one asset by id or slug: Remotion code files, the structured spec (params, timing, fonts, colors, reference frames), the agent prompt and its version hash. With a brand kit, the spec is restyled with the kit. Returning code counts as one pull (repeat pulls of the same version are free on the Free plan).

InputTypeRequiredDescription
asset_idstringyesAsset uuid or slug, e.g. word-pop-captions.
brand_kit_idstringnoBrand kit id from list_brand_kits, or "default". When given, the spec's fonts, colors, caption style and logo come from the kit and the asset carries a `brand_kit` field.
MCP input
{
  "asset_id": "focus-word-scroll",
  "brand_kit_id": "kit_7f3a9c21"
}
REST
curl "https://cutship.ai/api/v1/assets/focus-word-scroll?brand_kit_id=kit_7f3a9c21" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY"
Output
{
  "id": "3f2b8c1e-6a4d-4e2f-9b7a-1c5d8e0f2a64",
  "slug": "focus-word-scroll",
  "title": "Focus Word Scroll",
  "type": "component",
  "format": "captions",
  "preview_url": "https://cutship.ai/a/focus-word-scroll",
  "access": "free",
  "price_cents": 0,
  "creator": "cutship",
  "version": "9c41e07ab2d35f18",
  "code": {
    "files": [
      {
        "path": "components/remotion/focus-word-scroll/component.tsx",
        "content": "/* full source, ~200 lines */"
      },
      {
        "path": "components/remotion/focus-word-scroll/schema.ts",
        "content": "/* full source, ~200 lines */"
      },
      {
        "path": "components/remotion/brand-kit.ts",
        "content": "/* full source, ~200 lines */"
      }
    ],
    "dependencies": [
      "remotion"
    ]
  },
  "spec": {
    "slug": "focus-word-scroll",
    "name": "Focus Word Scroll",
    "type": "component",
    "creator": "cutship",
    "timing": {
      "fps": 30,
      "durationInFrames": 270,
      "seconds": 9,
      "width": 1080,
      "height": 1920,
      "aspectRatio": "9:16"
    },
    "params": [
      {
        "name": "words",
        "type": "array",
        "default": [],
        "description": "Word timestamps, e.g. from Whisper or @remotion/captions"
      },
      {
        "name": "wordsPerPage",
        "type": "integer",
        "default": 3,
        "min": 1,
        "max": 6,
        "description": "Max words shown at once"
      },
      {
        "name": "fontSize",
        "type": "number",
        "default": 64,
        "min": 40,
        "max": 160
      },
      {
        "name": "textColor",
        "type": "string",
        "default": "#F6F1EA"
      },
      {
        "name": "activeColor",
        "type": "string",
        "default": "#FF5A1F"
      }
    ],
    "fonts": [
      "Archivo Black"
    ],
    "colors": [
      {
        "param": "textColor",
        "value": "#F6F1EA"
      },
      {
        "param": "activeColor",
        "value": "#FF5A1F"
      }
    ],
    "referenceFrames": [
      {
        "frame": 0,
        "seconds": 0,
        "label": "start"
      },
      {
        "frame": 40,
        "seconds": 1.33,
        "label": "hero frame"
      },
      {
        "frame": 135,
        "seconds": 4.5,
        "label": "middle"
      },
      {
        "frame": 269,
        "seconds": 8.97,
        "label": "end"
      }
    ]
  },
  "prompt": "Add Focus Word Scroll to my Remotion video. Pass brandKit from brand-kit.ts…",
  "brand_kit": {
    "id": "kit_7f3a9c21",
    "name": "Northwind Coffee",
    "brandKit": {
      "fonts": [
        "Archivo Black",
        "Inter"
      ],
      "colors": [
        "#FF5A1F",
        "#1B1B1F",
        "#F6F1EA"
      ],
      "logo": "https://cutship.ai/storage/kits/northwind/logo.svg",
      "captionPosition": "bottom"
    }
  }
}

get_assets_batch

read (spec only) · pull (with code)

Get up to 100 assets in one call, optionally all styled with one brand kit. Each returned asset is a pull; assets you can't pull come back in `errors` with the reason.

InputTypeRequiredDescription
asset_idsstring[] (1–100 items)yesAsset uuids or slugs.
brand_kit_idstringnoBrand kit id from list_brand_kits, or "default". When given, the spec's fonts, colors, caption style and logo come from the kit and the asset carries a `brand_kit` field.
MCP input
{
  "asset_ids": [
    "focus-word-scroll",
    "halo-ring-stinger",
    "not-a-real-slug"
  ],
  "brand_kit_id": "kit_7f3a9c21"
}
REST
curl -X POST "https://cutship.ai/api/v1/assets/batch" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_ids":["focus-word-scroll","halo-ring-stinger","not-a-real-slug"],"brand_kit_id":"kit_7f3a9c21"}'
Output
{
  "assets": [
    {
      "slug": "focus-word-scroll",
      "version": "9c41e07ab2d35f18",
      "code": {
        "files": [
          "…"
        ],
        "dependencies": [
          "remotion"
        ]
      },
      "spec": {
        "…": "as in get_asset"
      }
    },
    {
      "slug": "halo-ring-stinger",
      "version": "e1d80a4c97b2f630",
      "code": {
        "files": [
          "…"
        ],
        "dependencies": [
          "remotion"
        ]
      },
      "spec": {
        "…": "as in get_asset"
      }
    }
  ],
  "errors": [
    {
      "id": "not-a-real-slug",
      "error": "Asset not found"
    }
  ]
}

list_brand_kits

read

List the brand kits you can use: personal kits, team kits and agency client kits, with which one is the default.

No input.

MCP input
{}
REST
curl "https://cutship.ai/api/v1/brand-kits" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY"
Output
{
  "brand_kits": [
    {
      "id": "kit_7f3a9c21",
      "name": "Northwind Coffee",
      "team": "Northwind Studio",
      "client_folder": null,
      "default": true
    },
    {
      "id": "kit_b20e5d47",
      "name": "Harbor Fitness",
      "team": "Northwind Studio",
      "client_folder": "Clients / Harbor",
      "default": false
    }
  ]
}

get_brand_kit

read

Get one brand kit as the JSON an agent styles with: logos, fonts and type scale, colors, caption style, pacing, transitions, layouts, templates, voice and the `brandKit` prop for Cutship components. kit_id may be "default".

InputTypeRequiredDescription
kit_idstringyesKit id or "default".
MCP input
{
  "kit_id": "default"
}
REST
curl "https://cutship.ai/api/v1/brand-kits/default" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY"
Output
{
  "id": "kit_7f3a9c21",
  "name": "Northwind Coffee",
  "team": "Northwind Studio",
  "clientFolder": null,
  "logos": [
    {
      "label": "Primary",
      "url": "https://cutship.ai/storage/kits/northwind/logo.svg"
    }
  ],
  "fonts": {
    "headline": "Archivo Black",
    "body": "Inter",
    "all": [
      "Archivo Black",
      "Inter"
    ]
  },
  "typeScale": {
    "headline": 96,
    "body": 42,
    "caption": 64
  },
  "colors": {
    "accent": "#FF5A1F",
    "all": [
      "#FF5A1F",
      "#1B1B1F",
      "#F6F1EA"
    ]
  },
  "captionStyle": {
    "position": "bottom",
    "notes": "Max 3 words per line; accent the active word."
  },
  "pacing": "Cut every 1.5–2s. The hook lands in the first second.",
  "transitions": [
    "pixel-reveal-transition",
    "light-leak-transition"
  ],
  "layouts": [
    {
      "label": "Talking head",
      "text": "Face in the upper two thirds, captions bottom, logo top-right at 6% width."
    }
  ],
  "templates": [],
  "voice": {
    "notes": "Warm, direct, no jargon.",
    "extra": []
  },
  "assets": [
    {
      "slug": "focus-word-scroll",
      "name": "Focus Word Scroll",
      "url": "https://cutship.ai/a/focus-word-scroll"
    }
  ],
  "boards": [
    {
      "id": "brd_51c0e9",
      "name": "Launch week"
    }
  ],
  "brandKit": {
    "fonts": [
      "Archivo Black",
      "Inter"
    ],
    "colors": [
      "#FF5A1F",
      "#1B1B1F",
      "#F6F1EA"
    ],
    "logo": "https://cutship.ai/storage/kits/northwind/logo.svg",
    "captionPosition": "bottom"
  }
}

get_board

read (spec only) · pull (with code) · Pro and up

Pull a whole board (a saved set of assets) as one style pack (Pro and up): a pack prompt plus every asset you can pull, kit-merged when a brand kit is given. Assets you can't pull are listed in `skipped`.

InputTypeRequiredDescription
board_idstringyes
brand_kit_idstringnoBrand kit id from list_brand_kits, or "default". When given, the spec's fonts, colors, caption style and logo come from the kit and the asset carries a `brand_kit` field.
MCP input
{
  "board_id": "brd_51c0e9",
  "brand_kit_id": "kit_7f3a9c21"
}
REST
curl "https://cutship.ai/api/v1/boards/brd_51c0e9?brand_kit_id=kit_7f3a9c21" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY"
Output
{
  "id": "brd_51c0e9",
  "name": "Launch week",
  "prompt": "Open on Halo Ring Stinger, Word Pop captions throughout, Liquid Mask between scenes.",
  "assets": [
    {
      "slug": "halo-ring-stinger",
      "…": "full asset"
    },
    {
      "slug": "focus-word-scroll",
      "…": "full asset"
    },
    {
      "slug": "pixel-reveal-transition",
      "…": "full asset"
    }
  ],
  "skipped": []
}

get_pack

read (spec only) · pull (with code)

Pull a pack: a private team pack (by id) or a creator style pack (by id or slug) with all its components, as one prompt plus assets. Same shape as get_board.

InputTypeRequiredDescription
pack_idstringyes
brand_kit_idstringnoBrand kit id from list_brand_kits, or "default". When given, the spec's fonts, colors, caption style and logo come from the kit and the asset carries a `brand_kit` field.
MCP input
{
  "pack_id": "soft-studio",
  "brand_kit_id": "kit_7f3a9c21"
}
REST
curl "https://cutship.ai/api/v1/packs/soft-studio?brand_kit_id=kit_7f3a9c21" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY"
Output
{
  "id": "pk_soft-studio",
  "name": "Soft Studio",
  "prompt": "Calm, editorial pacing. Soft Studio intro, serif titles, slow push-ins, warm grade.",
  "assets": [
    {
      "slug": "soft-studio-intro",
      "…": "full asset"
    },
    {
      "slug": "soft-studio-carousel",
      "…": "full asset"
    },
    {
      "slug": "soft-studio-poster",
      "…": "full asset"
    }
  ],
  "skipped": []
}

generate_variations

pull

Generate 1–50 distinct, deterministic variants of an asset's spec for A/B testing: alternate hooks, caption styles (position, case, emphasis), accent colors and timing (±10–25%). Each variant has a variant_id to pass to log_render and a `changes` list. Doesn't count as a pull.

InputTypeRequiredDescription
asset_idstringyesAsset uuid or slug.
brand_kit_idstringnoBrand kit id from list_brand_kits, or "default". When given, the spec's fonts, colors, caption style and logo come from the kit and the asset carries a `brand_kit` field.
countinteger (1–50)noDefault 5.
vary("hook" | "caption" | "color_accent" | "timing")[]noWhich dimensions to vary (default: all four).
MCP input
{
  "asset_id": "halo-ring-stinger",
  "brand_kit_id": "kit_7f3a9c21",
  "count": 20,
  "vary": [
    "hook",
    "color_accent"
  ]
}
REST
curl -X POST "https://cutship.ai/api/v1/assets/halo-ring-stinger/variations" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"brand_kit_id":"kit_7f3a9c21","count":20,"vary":["hook","color_accent"]}'
Output
{
  "asset_id": "halo-ring-stinger",
  "version": "e1d80a4c97b2f630",
  "variants": [
    {
      "variant_id": "var_01h9kq2",
      "spec": {
        "params": [
          {
            "name": "text",
            "default": "Your coffee is lying to you"
          },
          {
            "name": "accentColor",
            "default": "#FF5A1F"
          }
        ]
      },
      "changes": [
        "hook",
        "color_accent"
      ]
    },
    {
      "variant_id": "var_01h9kq3",
      "spec": {
        "params": [
          {
            "name": "text",
            "default": "3 beans. 1 winner."
          },
          {
            "name": "accentColor",
            "default": "#F6F1EA"
          }
        ]
      },
      "changes": [
        "hook",
        "color_accent"
      ]
    },
    "… 18 more"
  ]
}

reverse_inspo

read · Pro and up

Read the user's inspiration: a Pinterest board or pin (moving pins included), a TikTok/Reels/Shorts/YouTube link, a profile, and/or images. Returns the look broken down, the editing moves matched to Cutship assets (fit close/partial), the moves Cutship doesn't have yet as gaps with ids, and a brand-kit draft. The run is saved (inspo_id): turn a gap into a build brief with get_build_brief, build it, then save_asset. Pro and up.

InputTypeRequiredDescription
reference_urlstringnoOne link: a Pinterest board or pin, a TikTok/Reels/Shorts/YouTube post, or a profile.
reference_urlsstring[] (0–8 items)noSeveral links read together as one look (e.g. a few Pinterest pins).
imagesobject[] (0–12 items)noInspo images (screenshots, saved pins) as base64.
board_idstringnoThe Cutship board this is for (kept on the run).
MCP input
{
  "reference_url": "https://www.pinterest.com/you/night-street-board/",
  "board_id": "brd_51c0e9"
}
REST
curl -X POST "https://cutship.ai/api/v1/reverse-inspo" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reference_url":"https://www.pinterest.com/you/night-street-board/","board_id":"brd_51c0e9"}'
Output
{
  "inspo_id": "6f1d2c8a-3b4e-4a1f-9c7d-2e8b5a0f4c13",
  "kind": "look",
  "breakdown": {
    "color": "Crushed-black monochrome, lifted whites, fine grain. Palette: #0B0B0C, #F2F2F2",
    "pacing": "Still subjects against streaking backgrounds, punctuated by flash frames",
    "transitions": "Camera-flash whiteout (light and flash); CRT tear (glitch)"
  },
  "matches": [
    {
      "part": "CRT tear and black drop",
      "assets": [
        {
          "slug": "crt-chroma-credits",
          "title": "CRT Chroma Credits",
          "fit": "partial"
        }
      ]
    },
    {
      "part": "Floating panel stack",
      "assets": [
        {
          "slug": "photo-stack-tunnel",
          "title": "Photo Stack Tunnel",
          "fit": "partial"
        }
      ]
    }
  ],
  "gaps": [
    "Light and flash: Camera-flash whiteout. One or two frames blown to near-white, cutting back hard to a contrasty frame…"
  ],
  "gap_details": [
    {
      "gap_id": "g2",
      "part": "Light and flash",
      "name": "Camera-flash whiteout",
      "description": "One or two frames blown to near-white (#F2F2F2) with ghosted detail, cutting back hard to a contrasty black-and-white frame; irregular, like a paparazzi strobe."
    },
    {
      "gap_id": "g3",
      "part": "Speed and timing",
      "name": "Smeared drive-by hyperlapse",
      "description": "Footage sped up 2-4x with heavy directional blur so lights smear into streaks, easing back to real time on the subject."
    }
  ],
  "kit_draft": {
    "name": "Night street flash vibe",
    "fonts": [
      "Inter Tight"
    ],
    "colors": [
      "#0B0B0C",
      "#F2F2F2",
      "#E0301E"
    ],
    "pacing": "Restless, 1-3s loops"
  },
  "next": "Save close matches to a board… get_build_brief(inspo_id, gap_id)… save_asset with board_id."
}

get_build_brief

read · Pro and up

Turn one gap from reverse_inspo into a build brief for a new asset: name, category, format, timing, look, motion, props with defaults, acceptance checks, signed URLs of the reference frames, Cutship's rules for the three files, and file skeletons. Build it in the user's Remotion project, check stills against the reference frames, then save_asset. Pro and up.

InputTypeRequiredDescription
inspo_idstringyesFrom reverse_inspo.
gap_idstringyesA gap_id from reverse_inspo, e.g. g2.
MCP input
{
  "inspo_id": "6f1d2c8a-3b4e-4a1f-9c7d-2e8b5a0f4c13",
  "gap_id": "g2"
}
REST
curl -X POST "https://cutship.ai/api/v1/build-brief" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inspo_id":"6f1d2c8a-3b4e-4a1f-9c7d-2e8b5a0f4c13","gap_id":"g2"}'
Output
{
  "inspo_id": "6f1d2c8a-3b4e-4a1f-9c7d-2e8b5a0f4c13",
  "gap_id": "g2",
  "brief": {
    "name": "Flash Strobe Whiteout",
    "category": "Transitions",
    "asset_type": "component",
    "format": "transition",
    "aspect_ratio": "9:16",
    "fps": 30,
    "duration_frames": 24,
    "applies_to_footage": true,
    "look": "Frames blow out to #F2F2F2 with a faint ghost of the image, then snap back to high-contrast black and white…",
    "motion": "0-2: exposure ramps to white with Easing.in(Easing.exp); 2-4 hold; 4: hard cut back; optional second hit at 9-10…",
    "props": [
      {
        "name": "flashes",
        "type": "number",
        "default": "2",
        "options": [],
        "description": "How many strobe hits"
      }
    ],
    "acceptance": [
      "Frame 3 is near-white with ghosted detail",
      "Frame 5 is a hard return to the contrasty image"
    ],
    "reference_frames": [
      3,
      4,
      5
    ],
    "usage": "Put it on the cut between two clips; set flashes to 1 for a single camera flash."
  },
  "reference_frames": [
    "https://…supabase.co/storage/v1/object/sign/inspo/…/03.jpg?token=…"
  ],
  "rules": "Build it as a Remotion component in the Cutship format…",
  "skeleton": {
    "schema.ts": "import { z } from \"zod\";…",
    "meta.ts": "export const meta: ComponentMeta = {…}"
  },
  "save_with": {
    "tool": "save_asset",
    "args": {
      "inspo_id": "6f1d2c8a-…",
      "gap_id": "g2",
      "board_id": "brd_51c0e9"
    }
  }
}

save_asset

pull · writes to your account

Save an asset the agent built (component.tsx, schema.ts, meta.ts) to the user's Cutship account as a private asset, optionally straight onto a board. Static checks run first (imports, fonts, naming, meta); fix any failures and call again. Pass asset_id to save a new version of one of the user's private assets.

InputTypeRequiredDescription
filesanyyesThe three files: either { "component.tsx": "...", "schema.ts": "...", "meta.ts": "..." } or [{ path, content }].
board_idstringnoPut it on this board too.
inspo_idstringnoThe inspo run it was built from.
gap_idstringnoThe gap it fills.
asset_idstringnoUpdate this private asset instead of creating a new one.
MCP input
{
  "files": {
    "component.tsx": "/* … */",
    "schema.ts": "/* … */",
    "meta.ts": "/* … */"
  },
  "board_id": "brd_51c0e9",
  "inspo_id": "6f1d2c8a-…",
  "gap_id": "g2"
}
REST
curl -X POST "https://cutship.ai/api/v1/assets" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files":{"component.tsx":"/* … */","schema.ts":"/* … */","meta.ts":"/* … */"},"board_id":"brd_51c0e9","inspo_id":"6f1d2c8a-…","gap_id":"g2"}'
Output
{
  "asset_id": "0c9e4b1d-7a52-4f3e-8d6b-1a2f3c4d5e6f",
  "slug": "u-3fa9c1-flash-strobe-whiteout",
  "url": "https://cutship.ai/a/u-3fa9c1-flash-strobe-whiteout",
  "visibility": "private",
  "updated": false,
  "checks": [],
  "board": {
    "board_id": "brd_51c0e9",
    "added": true
  },
  "inspo": {
    "inspo_id": "6f1d2c8a-…",
    "gap_id": "g2"
  },
  "install": "npx cutship add u-3fa9c1-flash-strobe-whiteout"
}

list_boards

read

The user's boards (personal and team) with ids, names and asset counts.

No input.

MCP input
{}
REST
curl "https://cutship.ai/api/v1/boards" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY"
Output
{
  "boards": [
    {
      "board_id": "brd_51c0e9",
      "name": "Night street",
      "count": 7,
      "team": null,
      "default": false,
      "url": "https://cutship.ai/boards/brd_51c0e9"
    }
  ]
}

create_board

pull · writes to your account

Create a board on the user's account (returns the existing one if a board with that name already exists).

InputTypeRequiredDescription
namestringyes
MCP input
{
  "name": "Night street"
}
REST
curl -X POST "https://cutship.ai/api/v1/boards" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Night street"}'
Output
{
  "board_id": "brd_51c0e9",
  "name": "Night street",
  "url": "https://cutship.ai/boards/brd_51c0e9",
  "existed": false
}

add_to_board

pull · writes to your account

Add assets (live Cutship assets or the user's own private ones) to one of the user's boards.

InputTypeRequiredDescription
board_idstringyes
asset_idsstring[] (0–50 items)yesAsset uuids or slugs.
MCP input
{
  "board_id": "brd_51c0e9",
  "asset_ids": [
    "crt-chroma-credits",
    "halo-ring-stinger"
  ]
}
REST
curl -X POST "https://cutship.ai/api/v1/boards/brd_51c0e9/items" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_ids":["crt-chroma-credits","halo-ring-stinger"]}'
Output
{
  "board_id": "brd_51c0e9",
  "added": [
    "crt-chroma-credits",
    "halo-ring-stinger"
  ],
  "errors": [],
  "count": 2,
  "url": "https://cutship.ai/boards/brd_51c0e9"
}

save_brand_kit

pull · writes to your account

Save a brand kit on the user's account from a reverse_inspo kit_draft (or straight from an inspo_id). Kit limits apply.

InputTypeRequiredDescription
kit_draftobjectnokit_draft from reverse_inspo.
inspo_idstringno
namestringno
MCP input
{
  "inspo_id": "6f1d2c8a-3b4e-4a1f-9c7d-2e8b5a0f4c13",
  "name": "Night street flash"
}
REST
curl -X POST "https://cutship.ai/api/v1/brand-kits" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inspo_id":"6f1d2c8a-3b4e-4a1f-9c7d-2e8b5a0f4c13","name":"Night street flash"}'
Output
{
  "brand_kit_id": "kit_7f3a9c21",
  "name": "Night street flash",
  "url": "https://cutship.ai/brand-kit/kit_7f3a9c21"
}

get_taste_profile

read · Pro and up

Learn the look the user wants from what they already have (an inspo run from reverse_inspo, e.g. a Pinterest board; a Cutship board; a style pack; a brand kit; images; their own words) and turn it into a plan for a video: grade, camera, pacing, transitions, the Cutship assets that build it, and a shot list where every shot has stock search queries and an AI video prompt. Names of real people, brands and titles never appear in it; they come back in keep_out so they stay out of prompts. Follow `prompt` to make the video. Pro and up.

InputTypeRequiredDescription
inspo_idstringnoFrom reverse_inspo (a Pinterest board or pins, links or images it read).
board_idstringnoA Cutship board of saved assets.
pack_idstringnoA creator style pack (id or slug) or a team pack id.
brand_kit_idstringnoA brand kit to stay on (or "default").
imagesobject[] (0–8 items)noExtra inspo images as base64.
notesstringnoWhat the user wants in their words, e.g. "early 2000s, sunny, camcorder, skate and studio".
shotsinteger (3–16)noHow many shots to plan. Default 8.
length_sinteger (5–180)noTarget length in seconds. Default 20.
aspect_ratiostringnoOne of: 9:16, 16:9, 1:1, 4:5. Default "9:16".
MCP input
{
  "inspo_id": "6f1d2c8a-3b4e-4a1f-9c7d-2e8b5a0f4c13",
  "notes": "early 2000s, sunny, camcorder, skate and studio",
  "shots": 8,
  "length_s": 20
}
REST
curl -X POST "https://cutship.ai/api/v1/taste" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inspo_id":"6f1d2c8a-3b4e-4a1f-9c7d-2e8b5a0f4c13","notes":"early 2000s, sunny, camcorder, skate and studio","shots":8,"length_s":20}'
Output
{
  "taste": {
    "name": "Sunlit Y2K studio",
    "summary": "Bright, saturated early-2000s energy shot like a home camcorder: fisheye skate clips, studio sessions and candy colors…",
    "era": "Early-2000s hip-hop and skate culture: trucker caps, oversized tees, flip phones, chrome and candy colors",
    "look": {
      "colors": [
        "#FFD23F",
        "#3BCEAC",
        "#EE4266",
        "#0B0B0C"
      ],
      "fonts": [
        "Archivo Black",
        "Space Mono"
      ],
      "grade": "Punchy saturation, lifted blacks, slight cyan shadows, DV-camcorder softness and timestamp…",
      "camera": "Handheld, fisheye close-ups, low angles…"
    },
    "pacing": "Cut every 2 beats; hero shots hold a full bar; speed-ramp into the drop",
    "transitions": [
      "whip pan",
      "zoom through",
      "flash frame"
    ],
    "components": [
      {
        "slug": "cinematic-grade",
        "name": "Cinematic Grade",
        "role": "grade on every shot"
      },
      {
        "slug": "zoom-through-transition",
        "name": "Zoom Through Transition",
        "role": "into the montage on the drop"
      }
    ],
    "shots": [
      {
        "id": "s1",
        "purpose": "hook",
        "description": "The creator puts headphones on at their desk…",
        "queries": [],
        "ai_prompt": "…",
        "prefer": "own",
        "duration_s": 3
      },
      {
        "id": "s2",
        "purpose": "montage",
        "description": "A skateboarder kickflips past a sunny storefront, fisheye lens",
        "queries": [
          "skateboarder fisheye street",
          "skateboard trick sunny"
        ],
        "ai_prompt": "Handheld fisheye shot of a skateboarder…, early-2000s camcorder look",
        "prefer": "stock",
        "duration_s": 1.5
      }
    ],
    "avoid": [
      "Real people's likeness from the inspo",
      "Logos and brand marks",
      "Clean modern 4K sharpness"
    ],
    "keep_out": [
      "(names from the inspo)"
    ],
    "format": {
      "aspect_ratio": "9:16",
      "length_s": 20
    },
    "sources": {
      "inspo_id": "6f1d2c8a-3b4e-4a1f-9c7d-2e8b5a0f4c13"
    }
  },
  "prompt": "Make a 20s 9:16 video in the \"Sunlit Y2K studio\" taste with Cutship.\n1. Install the components…",
  "rights_rules": [
    "Only usable-lane media goes into a render…"
  ],
  "stock": {
    "ready": true,
    "providers": [
      "pexels",
      "pixabay"
    ]
  },
  "next": "Call source_media with taste.shots…"
}

source_media

read · Pro and up

Find licensed stock footage (Pexels, Pixabay) for a taste profile's shots, ranked against each shot, every candidate with a rights record (license, commercial use, attribution, people). Shots stock can't cover come back in ai_fallback with their AI prompt, for your own video-generation tool. Pass ids instead to fetch exact candidates (with download URLs) you picked. Download with `npx cutship get-media`, then run `npx cutship rights check` before rendering. Pro and up.

InputTypeRequiredDescription
shotsobject[] (0–12 items)notaste.shots from get_taste_profile (id, queries, description, duration_s, prefer, ai_prompt).
querystringnoOne free-text search instead of shots.
idsstring[] (0–30 items)noExact candidates to fetch, e.g. "pexels:video:123".
kind"video" | "photo"noDefault "video".
orientationstringnoOne of: portrait, landscape, square, any. Default "portrait".
per_shotinteger (1–15)noDefault 6.
sources("pexels" | "pixabay")[]noLimit to these libraries.
search_ai_shotsbooleannoAlso search stock for shots that prefer AI. Default false.
MCP input
{
  "shots": [
    {
      "id": "s2",
      "queries": [
        "skateboarder fisheye street",
        "skateboard trick sunny"
      ],
      "prefer": "stock",
      "duration_s": 1.5
    }
  ],
  "orientation": "portrait",
  "per_shot": 6
}
REST
curl -X POST "https://cutship.ai/api/v1/source" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shots":[{"id":"s2","queries":["skateboarder fisheye street","skateboard trick sunny"],"prefer":"stock","duration_s":1.5}],"orientation":"portrait","per_shot":6}'
Output
{
  "shots": [
    {
      "id": "s2",
      "queries_used": [
        "skateboarder fisheye street",
        "skateboard trick sunny"
      ],
      "weak": false,
      "candidates": [
        {
          "id": "pexels:video:856789",
          "source": "pexels",
          "kind": "video",
          "title": "man skateboarding on a sunny street",
          "preview_url": "https://images.pexels.com/videos/856789/…jpeg",
          "page_url": "https://www.pexels.com/video/man-skateboarding-on-a-sunny-street-856789/",
          "duration_s": 12,
          "width": 1080,
          "height": 1920,
          "download": {
            "url": "https://videos.pexels.com/video-files/856789/…mp4",
            "width": 1080,
            "height": 1920,
            "quality": "hd"
          },
          "score": 0.61,
          "rights": {
            "lane": "usable",
            "source": "pexels",
            "license": "Pexels License",
            "commercial_use": true,
            "editorial": false,
            "attribution": "appreciated",
            "people": "likely",
            "author": "…",
            "notes": [
              "Don't imply that people, brands or places in it endorse you or your product."
            ]
          }
        }
      ]
    }
  ],
  "ai_fallback": [
    {
      "id": "s5",
      "ai_prompt": "…",
      "reason": "Stock has nothing close for this shot."
    }
  ],
  "own": [
    "s1"
  ],
  "providers": [
    "pexels",
    "pixabay"
  ],
  "missing": [],
  "attribution": "Results come from Pexels and Pixabay…",
  "rights_rules": [
    "…"
  ],
  "next": "Look at each candidate's preview_url… `npx cutship get-media <id…>`…"
}

log_render

pull

Report renders you made with an asset (and variant). Call after every render batch: renders feed your usage and pay the asset's creator.

InputTypeRequiredDescription
asset_idstringyesAsset uuid or slug.
variant_idstringnoFrom generate_variations, if a variant was rendered.
countinteger (1–100000)noDefault 1.
platformstringnoWhere it will be posted, e.g. tiktok, reels, shorts, youtube, x, linkedin.
brand_kit_idstringnoThe kit the render used.
MCP input
{
  "asset_id": "halo-ring-stinger",
  "variant_id": "var_01h9kq2",
  "count": 1,
  "platform": "tiktok",
  "brand_kit_id": "kit_7f3a9c21"
}
REST
curl -X POST "https://cutship.ai/api/v1/renders" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"asset_id":"halo-ring-stinger","variant_id":"var_01h9kq2","count":1,"platform":"tiktok","brand_kit_id":"kit_7f3a9c21"}'
Output
{
  "logged": 1,
  "period_renders": 1284
}

get_usage

read

This billing period's usage: pulls used vs your plan's limit, renders, requests per minute, top assets and a by-day series.

No input.

MCP input
{}
REST
curl "https://cutship.ai/api/v1/usage" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY"
Output
{
  "period": {
    "start": "2026-11-01",
    "end": "2026-11-30"
  },
  "tier": "pro",
  "pulls": {
    "used": 212,
    "limit": null
  },
  "renders": 1284,
  "requests_per_minute": 60,
  "by_asset": [
    {
      "slug": "focus-word-scroll",
      "pulls": 3,
      "renders": 940
    },
    {
      "slug": "halo-ring-stinger",
      "pulls": 2,
      "renders": 344
    }
  ]
}

get_clip_kit

read (spec only) · pull (with code)

Everything a clipping pipeline needs in one call, styled with a brand kit: captions, hook overlays, progress bars, speaker labels, reframe rules and stingers (each a list of full assets with code), plus a prompt for turning long videos into branded clips. Each asset returned with code is a pull.

InputTypeRequiredDescription
brand_kit_idstringnoBrand kit id from list_brand_kits, or "default". When given, the spec's fonts, colors, caption style and logo come from the kit and the asset carries a `brand_kit` field.
MCP input
{
  "brand_kit_id": "kit_7f3a9c21"
}
REST
curl "https://cutship.ai/api/v1/clip-kit?brand_kit_id=kit_7f3a9c21" \
  -H "Authorization: Bearer $CUTSHIP_API_KEY"
Output
{
  "brand_kit": {
    "id": "kit_7f3a9c21",
    "name": "Northwind Coffee",
    "brandKit": {
      "fonts": [
        "Archivo Black",
        "Inter"
      ],
      "colors": [
        "#FF5A1F",
        "#1B1B1F",
        "#F6F1EA"
      ],
      "logo": "https://cutship.ai/storage/kits/northwind/logo.svg",
      "captionPosition": "bottom"
    }
  },
  "captions": [
    {
      "slug": "focus-word-scroll",
      "format": "captions",
      "…": "full asset, kit-merged"
    }
  ],
  "overlays": [
    {
      "slug": "focus-word-scroll",
      "format": "hook_overlay",
      "…": "full asset"
    },
    {
      "slug": "list-wheel",
      "format": "hook_overlay",
      "…": "full asset"
    }
  ],
  "progress_bars": [
    {
      "slug": "face-reframe",
      "format": "progress_bar",
      "…": "full asset"
    }
  ],
  "speaker_labels": [
    {
      "slug": "slot-selector",
      "format": "speaker_label",
      "…": "full asset"
    }
  ],
  "reframe_rules": [
    {
      "slug": "focus-zoom",
      "format": "reframe",
      "…": "full asset"
    }
  ],
  "stingers": [
    {
      "slug": "light-leak-transition",
      "format": "stinger",
      "…": "full asset"
    }
  ],
  "prompt": "Cut the source into 30–60s clips. Reframe 16:9 → 9:16 keeping the speaker centered…"
}

The stdio server (npx cutship mcp) also keeps apply_style_pack(slug, brand_kit_id?), an alias of get_pack, for agents set up before v1.

Clipping

Clip formats are the layers that turn long-form footage (podcasts, webinars, talking heads) into short on-brand clips. get_clip_kit returns one array per format, every asset already merged with your brand kit, plus a prompt that tells the agent how to assemble them.

KeyFormatWhat it isExample
captionscaptionsWord-level animated captions driven by a timestamp array (Whisper, @remotion/captions).word-pop-captions, marker-highlight-captions
overlayshook_overlayThe first-second hook: a headline or typed line over the footage.hook-title, typewriter-hook, kinetic-headline
progress_barsprogress_barA watch-time bar so viewers see how long is left.progress-bar
speaker_labelsspeaker_labelName and title lower thirds for each speaker.glass-lower-third, lower-third
reframe_rulesreframeHow to go 16:9 → 9:16: crop box, speaker tracking, punch-ins, safe areas for captions.focus-zoom, punch-in-zoom
stingersstingerShort branded transitions between cuts and at the end.light-leak-transition, liquid-mask-transition

Kit-merged means the spec defaults already use your fonts, colors, caption position and pacing, and brand_kit.brandKit is ready to pass as the brandKit prop. Search for more clip assets with search_assets and format set to one of the formats above.

End-to-end example

Pull brand kit → get clip kit → generate 20 variations → render in Remotion → log_render. With an agent, the whole thing is one prompt:

prompt
Use the cutship MCP. Pull my default brand kit and its clip kit, write the captions,
hook overlay and progress bar into src/, generate 20 variations of the hook,
render each with npx remotion render (composition BrandedClip, footage public/source.mp4),
and log_render every finished file.

Which runs these MCP calls:

MCP calls
1. get_brand_kit        { "kit_id": "default" }
2. get_clip_kit         { "brand_kit_id": "kit_7f3a9c21" }
   → write captions[0], overlays[0], progress_bars[0] code into src/
3. generate_variations  { "asset_id": "kinetic-headline", "brand_kit_id": "kit_7f3a9c21",
                          "count": 20, "vary": ["hook", "color_accent"] }
4. (shell) npx remotion render src/index.ts BrandedClip out/<variant_id>.mp4 --props=out/<variant_id>.json
5. log_render           { "asset_id": "kinetic-headline", "variant_id": "<variant_id>",
                          "count": 1, "platform": "tiktok", "brand_kit_id": "kit_7f3a9c21" }

The same pipeline as a script against the REST API. It assumes a Remotion project with a BrandedClip composition that layers your footage with the three components and takes brandKit, captions, hook and progress props, and a words.json transcript.

pipeline.ts
// pipeline.ts — Node 20+. Run: CUTSHIP_API_KEY=ck_… npx tsx pipeline.ts
import { execFileSync } from "node:child_process";
import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
import path from "node:path";

const API = "https://cutship.ai/api/v1";

async function cutship<T>(route: string, body?: unknown): Promise<T> {
  for (;;) {
    const res = await fetch(API + route, {
      method: body ? "POST" : "GET",
      headers: { Authorization: `Bearer ${process.env.CUTSHIP_API_KEY}`, "Content-Type": "application/json" },
      body: body ? JSON.stringify(body) : undefined,
    });
    if (res.status === 429) {
      // Back off for retry_after seconds, then try again.
      const { retry_after } = await res.json();
      await new Promise((r) => setTimeout(r, retry_after * 1000));
      continue;
    }
    const data = await res.json();
    if (!res.ok) throw new Error(`${data.code}: ${data.error}`);
    return data as T;
  }
}

type Spec = { params: { name: string; default: unknown }[] };
type Asset = { id: string; slug: string; version: string; spec: Spec; code: { files: { path: string; content: string }[] } };
const propsOf = (spec: Spec) => Object.fromEntries(spec.params.map((p) => [p.name, p.default]));

// 1. Brand kit
const kit = await cutship<{ id: string; brandKit: Record<string, unknown> }>("/brand-kits/default");

// 2. Clip kit, already merged with the kit
const clip = await cutship<{ captions: Asset[]; overlays: Asset[]; progress_bars: Asset[] }>(
  `/clip-kit?brand_kit_id=${kit.id}`,
);
const [captions, hook, progress] = [clip.captions[0], clip.overlays[0], clip.progress_bars[0]];
for (const asset of [captions, hook, progress]) {
  for (const f of asset.code.files) {
    const target = path.join("src", f.path);
    mkdirSync(path.dirname(target), { recursive: true });
    writeFileSync(target, f.content);
  }
}

// 3. 20 variations of the hook overlay
const { variants } = await cutship<{ variants: { variant_id: string; spec: Spec }[] }>(
  `/assets/${hook.slug}/variations`,
  { brand_kit_id: kit.id, count: 20, vary: ["hook", "color_accent"] },
);

// 4. Render each variant with Remotion, then 5. log it
const words = JSON.parse(readFileSync("words.json", "utf8")); // [{ text, startMs, endMs }] from Whisper
mkdirSync("out", { recursive: true });
for (const v of variants) {
  const props = {
    brandKit: kit.brandKit,
    captions: { ...propsOf(captions.spec), words },
    hook: propsOf(v.spec),
    progress: propsOf(progress.spec),
  };
  writeFileSync(`out/${v.variant_id}.json`, JSON.stringify(props));
  execFileSync("npx", ["remotion", "render", "src/index.ts", "BrandedClip", `out/${v.variant_id}.mp4`, `--props=out/${v.variant_id}.json`], { stdio: "inherit" });
  await cutship("/renders", { asset_id: hook.id, variant_id: v.variant_id, count: 1, platform: "tiktok", brand_kit_id: kit.id });
}
await cutship("/renders", { asset_id: captions.id, count: variants.length, platform: "tiktok", brand_kit_id: kit.id });
await cutship("/renders", { asset_id: progress.id, count: variants.length, platform: "tiktok", brand_kit_id: kit.id });

Rate limits & tiers

PlanPullsRequests / min
Free5 per month10
ProUnlimited60 per key
Pro+Unlimited60 per key
TeamUnlimited120, shared by the team
AgencyUnlimited300, shared
VolumeUnlimitedCustom per key (600 shared by default)

Over the limit you get a 429 with a Retry-After header and this body. The stdio server passes retry_after and upgrade_url through in the tool error so your agent can wait or tell you.

429
HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0

{
  "error": "Rate limit of 10 requests/min reached. Retry in 12s, or upgrade for a higher limit.",
  "code": "rate_limited",
  "retry_after": 12,
  "upgrade_url": "https://cutship.ai/pricing"
}

When a Free account uses its 5 pulls, pulls return limit_reached with the same upgrade_url; search, brand kits and usage keep working. See pricing for plans, or talk to us about Volume for pipelines rendering thousands of videos a day.

Caching & versioning

  • Every asset has a version: the first 16 hex characters of a SHA-256 of its code and spec. Search results include it, so you can check for changes without pulling.
  • Cache pulled code by slug + version (+ brand_kit_id if you merge a kit). Re-fetch only when the version changes.
  • Repeat pulls of the same version by the same key in a billing period count once, so re-running a pipeline doesn’t burn pulls.
  • Renders are counted separately, through log_render. Log every finished video (pass count to log a batch in one call); it keeps your usage accurate and pays the creators whose assets you render.
  • get_usage shows pulls, renders and your current rate limit for the period.

Errors

Errors are JSON with a human message and a stable code. Branch on code; show error to people.

error
{
  "error": "This key has scope \"read\"; this needs \"pull\". Create a pull key in Dashboard → API keys.",
  "code": "forbidden"
}
codeWhenWhat to do
unauthorizedMissing, revoked or mistyped key.Send Authorization: Bearer ck_…; create a key in Dashboard → API keys.
forbiddenThe key's scope doesn't cover this call (e.g. a read key asking for code).Use a pull key.
not_foundNo asset, kit, board or pack with that id or slug for this key.Check the slug with search_assets or list_brand_kits.
upgrade_requiredThe feature needs a higher plan (reverse_inspo needs Pro), or the asset is paid.Follow upgrade_url.
limit_reachedFree monthly pulls are used up.Wait for the next period or upgrade.
rate_limitedToo many requests this minute.Wait retry_after seconds.
bad_requestMissing or invalid input (e.g. count above 50, more than 100 batch ids).Fix the input; the message says which field.