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.
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.
Scope
Can
read
Search, list brand kits, get specs and prompts without code, usage, reverse inspo.
pull
Everything in read, plus code, generate_variations and log_render.
admin
Everything in pull, plus managing keys through the API.
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.
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.
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.
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.
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.
Input
Type
Required
Description
query
string
no
Free text, e.g. "word pop captions" or "chrome logo".
reference_url
string
no
A TikTok/Reels/YouTube URL whose style to match (Pro and up).
format
string
no
What 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.
vibe
string
no
A mood or aesthetic, e.g. "y2k chrome", "soft studio", "bold".
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).
Input
Type
Required
Description
asset_id
string
yes
Asset uuid or slug, e.g. word-pop-captions.
brand_kit_id
string
no
Brand 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.
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.
Input
Type
Required
Description
asset_ids
string[] (1–100 items)
yes
Asset uuids or slugs.
brand_kit_id
string
no
Brand 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.
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".
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`.
Input
Type
Required
Description
board_id
string
yes
brand_kit_id
string
no
Brand 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.
{
"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.
Input
Type
Required
Description
pack_id
string
yes
brand_kit_id
string
no
Brand 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.
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.
Input
Type
Required
Description
asset_id
string
yes
Asset uuid or slug.
brand_kit_id
string
no
Brand 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.
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.
Input
Type
Required
Description
reference_url
string
no
One link: a Pinterest board or pin, a TikTok/Reels/Shorts/YouTube post, or a profile.
reference_urls
string[] (0–8 items)
no
Several links read together as one look (e.g. a few Pinterest pins).
{
"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.
{
"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.
Input
Type
Required
Description
files
any
yes
The three files: either { "component.tsx": "...", "schema.ts": "...", "meta.ts": "..." } or [{ path, content }].
board_id
string
no
Put it on this board too.
inspo_id
string
no
The inspo run it was built from.
gap_id
string
no
The gap it fills.
asset_id
string
no
Update this private asset instead of creating a new one.
Save a brand kit on the user's account from a reverse_inspo kit_draft (or straight from an inspo_id). Kit limits apply.
Input
Type
Required
Description
kit_draft
object
no
kit_draft from reverse_inspo.
inspo_id
string
no
name
string
no
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.
Input
Type
Required
Description
inspo_id
string
no
From reverse_inspo (a Pinterest board or pins, links or images it read).
board_id
string
no
A Cutship board of saved assets.
pack_id
string
no
A creator style pack (id or slug) or a team pack id.
brand_kit_id
string
no
A brand kit to stay on (or "default").
images
object[] (0–8 items)
no
Extra inspo images as base64.
notes
string
no
What the user wants in their words, e.g. "early 2000s, sunny, camcorder, skate and studio".
{
"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.
Input
Type
Required
Description
shots
object[] (0–12 items)
no
taste.shots from get_taste_profile (id, queries, description, duration_s, prefer, ai_prompt).
query
string
no
One free-text search instead of shots.
ids
string[] (0–30 items)
no
Exact candidates to fetch, e.g. "pexels:video:123".
kind
"video" | "photo"
no
Default "video".
orientation
string
no
One of: portrait, landscape, square, any. Default "portrait".
per_shot
integer (1–15)
no
Default 6.
sources
("pexels" | "pixabay")[]
no
Limit to these libraries.
search_ai_shots
boolean
no
Also search stock for shots that prefer AI. Default false.
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.
Input
Type
Required
Description
brand_kit_id
string
no
Brand 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.
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.
Key
Format
What it is
Example
captions
captions
Word-level animated captions driven by a timestamp array (Whisper, @remotion/captions).
word-pop-captions, marker-highlight-captions
overlays
hook_overlay
The first-second hook: a headline or typed line over the footage.
hook-title, typewriter-hook, kinetic-headline
progress_bars
progress_bar
A watch-time bar so viewers see how long is left.
progress-bar
speaker_labels
speaker_label
Name and title lower thirds for each speaker.
glass-lower-third, lower-third
reframe_rules
reframe
How to go 16:9 → 9:16: crop box, speaker tracking, punch-ins, safe areas for captions.
focus-zoom, punch-in-zoom
stingers
stinger
Short 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.
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.
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 });
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.
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.