Developer docs

Anything the Concat window can do to a project, your program can do through the Concat API, over JSON-RPC, MCP or gRPC.

Pick a page

I want to…Go to
See a working example in 30 secondsQuick start below
Understand the model: sessions, jobs, errorsAPI overview
Look up a method and its replyMethods
Make an edit (add a clip, trim, title, effect)Edit commands
Know what a clip / project / package looks like as JSONTypes
Script Concat over stdin or a socketJSON-RPC
Use generated clients over HTTP/2gRPC
Connect an AI agent (Model Context Protocol)MCP
Copy-paste a whole scriptRecipes

Quick start

Important

What ships: every desktop release serves JSON-RPC from the window's Settings › Automation page while the editor is open, and is an MCP server for AI agents when started as concat --mcp. concat-cli and gRPC come only with a build from source; no release ships them.

1. Run one call. From a source checkout:

cd src
cargo run -p concat-cli -- api '{"method":"version"}'
{
  "jsonrpc": "2.0",
  "id": null,
  "result": {
    "apiVersion": "0.2",
    "concat": "0.2.11",
    "dirs": { "config": "…", "data": "…" },
    "capabilities": ["events"]
  }
}

2. Make a video. Put these lines in edit.jsonl and pipe them in with cargo run -p concat-cli -- api < edit.jsonl:

{"jsonrpc":"2.0","id":1,"method":"project.create","params":{"location":"/edits","name":"Reel"}}
{"jsonrpc":"2.0","id":2,"method":"media.import","params":{"path":"/edits/Reel","file":"/footage/take1.mp4"}}
{"jsonrpc":"2.0","id":3,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addClipAtFirstFree","mediaId":"m1","start":0}}}
{"jsonrpc":"2.0","id":4,"method":"edit.apply","params":{"path":"/edits/Reel","command":{"op":"addTextClip","start":1,"style":{"content":"Hello"}}}}
{"jsonrpc":"2.0","id":5,"method":"export.run","params":{"path":"/edits/Reel","output":"/edits/reel.mp4"}}

3. Watch it finish. The export answers at once with a job name, then reports as events until it is done:

{"jsonrpc":"2.0","id":5,"result":{"job":"j1","path":"/edits/Reel","output":"/edits/reel.mp4"}}
{"jsonrpc":"2.0","method":"export.progress","params":{"job":"j1","path":"/edits/Reel","frame":30,"total":150,"stage":"video"}}
{"jsonrpc":"2.0","method":"export.done","params":{"job":"j1","path":"/edits/Reel","output":"/edits/reel.mp4","width":1920,"height":1080}}

Tip

The same lines work over a socket. concat-cli serve listens on 127.0.0.1:7420, and the window's Settings › Automation page serves the same API while the editor is open, in every desktop release. See JSON-RPC.

The three ways in

TransportHow you reach itStatus
JSON-RPC 2.0 linesThe window's Automation page; from source, concat-cli api (stdin) and concat-cli serve (TCP or Unix socket)In every desktop release, from the window. The CLI needs a build from source
MCP over stdioconcat --mcp: the app as an MCP server, its tools generated from the API's typesIn every desktop release, since 0.2.8. See MCP
gRPC over HTTP/2concat-cli serve --grpc, in a build with the grpc featureBuild from source only

JSON-RPC and gRPC carry the same methods, payloads and errors. A method added to the API reaches every transport without a change to any of them. The MCP server's tools are the same methods and edit commands, with schemas generated from the API's types.

Five things to know

  1. Call version first. Its capabilities list says what this build serves.
  2. Projects are folders. Every method names a project by its folder path, and the folder must be open (project.open) first.
  3. Edits are commands. edit.apply carries the window's own edit vocabulary, unchanged. Same clamps, same refusals.
  4. Exports are jobs. export.run returns at once; progress comes as events; one export runs at a time.
  5. Errors have codes. Branch on code (notOpen, refused, busy…); show message to a person.

Where the code is

PiecePath
The contract: methods, payloads, events, errorssrc/crates/concat-api/src/message.rs
The dispatcher that runs themsrc/crates/concat-api/src/lib.rs
The JSON-RPC envelopesrc/crates/concat-api/src/rpc.rs
The socket server: JSON-RPC lines, gRPC, tokenssrc/crates/concat-server/
The MCP server behind concat --mcpsrc/crates/concat-mcp/
The gRPC service definitionsrc/crates/concat-server/proto/concat.proto
The CLI: api and serve, plus the engine tools probe, render, preview and checksrc/crates/concat-cli/src/main.rs
The edit commandssrc/crates/concat-project/src/commands/mod.rs

Related reading: ARCHITECTURE.md places the API in the engine.

Licensing

Concat is AGPL-3.0-or-later. A program that talks to it over this API is a client. A plugin built on the API may carry its own licence under LICENSE-EXCEPTIONS.md.

Keeping these pages true

Every method, edit command and type has a page of its own, built from the contract the app prints with concat --schema (see the contract as JSON Schema): its parameters and fields, their types, defaults and descriptions are the app's own. A new command appears here with its fields the day the schema is synced, and the site does not build while a page names something the app no longer has. The prose around them (what a method is for, examples, caveats) lives in the website repository under src/content. The apiVersion a build reports is API_VERSION in message.rs; the rules for bumping it are in the overview.