The API behind the library.
Read tags, summaries, chapters, transcripts, and playback links for any video. One Bearer key, JSON out, no browser.
curl https://studio.cutsio.com/api/v1/videos/<video-id> \
-H "Authorization: Bearer ak_..."Included with Studio and Enterprise. Keys live in Profile → Cutsio API Keys.
Everything the library knows, in JSON.
The same surface the CLI and every no-code automation uses. No SDK required — any HTTP client works.
/v1/videos/{id}Tags, custom metadata, summary, chapters, key moments, capture metadata, app URL, and public playback links for one asset.
/v1/videos/{id}Update title, tags, custom metadata, collection, or folder in one revision. Returns the updated asset and emits video.updated.
/v1/videos/{id}/transcriptThe transcript as VTT, SRT, TXT, or JSON. Ready for RAG, captions, or a CMS.
/v1/workspace/manifestFolder tree, collections, and a cursor-paged video list with a monotonic version for change detection.
/v1/workspace/usageActive plan and live balances: storage left and used, AI indexing minutes, AI credits, vertical-reframe minutes, and seats.
/v1/searchSemantic transcript search. Returns timestamped chunks grouped by video, with relevance scores.
/v1/videos/downloadBatch temporary master/mezzanine URLs for up to 50 videos. Idempotent; poll until ready.
/v1/uploadsCreate a video row and multipart upload, then request part URLs and complete the upload. Requires the write scope.
curl -X PATCH https://studio.cutsio.com/api/v1/videos/<video-id> \
-H "Authorization: Bearer ak_..." \
-H "Content-Type: application/json" \
-d '{
"tags": ["launch", "crowd"],
"custom_metadata": { "client": "Acme", "rating": 5 }
}'One revision, one event.
Only the fields you send change, and the whole patch is applied in one write. A real edit bumps the asset revision and emits video.updated with the changed fields. A no-op save returns changes: [] and stays silent.
Requires assets:write. Read-only keys are rejected before any write.
An asset your automation can act on.
The response carries what the pipeline needs — and nothing it does not. No Mux asset ids, no uploader ids, no internal moderation scores.
{
"id": "vid_...",
"title": "Launch day crowd",
"status": "ready",
"duration_ms": 12345,
"tags": ["launch", "crowd", "outdoor"],
"custom_metadata": { "client": "Acme", "rating": 5 },
"summary": "A launch event with a crowd...",
"chapters": [
{ "start_time": 0, "title": "Intro" }
],
"key_moments": [],
"transcript_state": "ready",
"app_url": "https://studio.cutsio.com/videos/vid_...",
"playback": {
"hls_url": "https://stream.mux.com/....m3u8",
"thumbnail_url": "https://image.mux.com/....jpg"
}
}Keys and scopes
- Keys are personal and follow your workspace memberships; use ?org= if you belong to more than one
- assets:read covers list, asset, transcript, search, download, and workspace usage
- assets:write is required for uploads and metadata edits — read-only keys are rejected before any write
- The secret is shown once at creation; revoke instantly from the same page
Pair it with webhooks
video.ready is the wake-up call; the API is the current state. metadata.ready carries the generated summary in its payload, with current tags on video.tags.
API vs CLI vs MCP
- API — any HTTP client: n8n, Make, Zapier, a script, your backend
- CLI — the same API packaged for agents, sync, transcripts, and uploads
- MCP — OAuth inside Claude, ChatGPT, Cursor, or VS Code; search and organize only
- Webhooks — push notifications; pair them with the API for current state
Built to be boring
- Bearer-token auth, one header, no OAuth dance for server-to-server
- JSON in and out, with clear 401 / 403 / 404 / 409 / 429 / 502 errors
- Per-user rate limits; 429 responses carry Retry-After
- Temporary signed URLs for masters; public playback URLs stay optional
Questions.
How do I get an API key?
Any workspace member opens Profile → Cutsio API Keys and creates a personal key. The secret is shown once. Send it as Authorization: Bearer ak_… on every request.
What is the difference between read-only and read-write keys?
Read-only keys carry assets:read and can list, read, search, download, and check plan usage. Keys created with upload access also carry assets:write. A read-only key is rejected before it can create a video row or an upload.
Which plan includes the API?
The public API is included with the Studio and Enterprise plans, the same gate as the MCP server and outbound webhooks. Any member can create a personal key; the workspace plan must be eligible.
How does the API relate to webhooks?
Webhooks tell you something changed; the API is how you fetch or update state. video.ready often fires before AI metadata exists. Subscribe to metadata.ready to receive the generated summary text in the payload; tags are in video.tags. Manual edits through PATCH /v1/videos/{id} emit video.updated.
Can I use my key across workspaces?
Yes. Keys are personal and follow your workspace memberships. If you belong to more than one workspace, pass ?org=<id-or-slug> or the x-cutsio-org header. Removing you from a workspace removes that key’s access automatically.
What are the rate limits?
Limits are per user, per minute: 240 asset reads, 120 transcript reads, 60 manifest pages, 60 usage reads, 120 updates, 120 searches, 30 download batches, and 60 upload calls. A 429 response carries Retry-After.
Do playback links expose the original file?
No. playback.hls_url is a public-policy Mux stream, not the master file. Downloading originals is a separate, authenticated flow through /v1/videos/download.
Related features
Discover more ways Cutsio can help your team work with video.
CLI for Agents
The footage backend for coding agents — semantic transcript search, one-command sync of mezzanine masters, and sidecar transcripts for RAG. One API key, JSON-first, idempotent.
MCP Server
Connect Claude, ChatGPT, Cursor, or VS Code to your Cutsio library — search assets and transcripts, browse collections and folders, and file videos into folders in plain language.
Webhooks
Signed outbound webhooks for video.ready, video.failed, metadata.ready, transcript.ready, transcript.skipped, and transcript.failed. Svix delivery with retries, replay, and test events. Studio and Enterprise plans.
Media Asset Management
Import, organize, search, and share your video library — with enterprise RAW pair backup for ARRI and RED workflows.
Content Teams
One searchable library for YouTube and studio teams — collaborate on footage, repurpose long-form into Shorts with AI, and hand off to DaVinci or Final Cut.
Give your pipeline the library.
One key, eleven endpoints, and the same metadata the app sees.