Martini Workflows API

The Workflows API executes reusable processes you have saved in Martini. The API starts runs with your material, reports their progress, and hands back the output files. It does not author or edit workflows; do that on a canvas in Martini, or through the MCP connector.

The same API key serves the Generation API. Every workflow route lives under https://api.martini.film/v1.

A workflow is a reusable production task saved in your workspace: its steps, the variables it reads, and the bins it expects material in. A run is one complete execution—like rolling the camera. Every run starts from a fresh copy of the workflow with the material you pass; running it again with the same material can produce a new variation without requiring any change to the workflow.

One workflow can have many runs. Each run has its own inputs, canvas, progress, spend, and outputs.

To try the calls without writing code, open the playground: paste a key, pick a workflow, start a run, and read the curl for each request.

Send the key as Authorization: Bearer <key>. The Generation API's Authorization: Key <key> form is accepted too, so one client can serve both. Requests belong to the key's organization; anything outside it reads as 404, never 403, so ids from another workspace cannot be probed.

An optional X-Martini-API-Version: 2026-08-13 header pins the response envelope. The served version is echoed back on every response. Runs act as the key's creator: for a placed workflow, or a projectId you name, that user must be able to edit the project, and the project's organization must have workflows enabled.

A workflow's inputs are what its briefs reference: canvas variables (a script, a character description, a product name) and the bins it reads that nothing in the chain writes (reference frames, source clips). GET /v1/workflows lists them: a saved workflow from its definition (variables with their saved defaults, bins by name), a placed workflow with the canvas state as it stands.

bins carries the material: keys are bin names (case-insensitive) or ids, values are asset ids in the order the Action should read them. A run of a saved workflow starts from empty bins, so every input bin must be pinned (WORKFLOW_BIN_REQUIRED otherwise). Assets must be completed and in a project the key's user can read: your uploads (POST /assets/uploads/…, which land in the API Generations project), the projectId you passed, or an earlier run's output in Workflow runs. Each is copied into the run's canvas as a new record on the same storage objects. A placed workflow reads the canvas bins you do not pin; pinned assets must be in its project.

An input bin can declare a fileInput (shown on the bin in GET /v1/workflows: its key, the format json, and whether it takes one file or many). Fill it with inputs instead of bins: keys are the declared keys, values are { "json": document } to send the document itself (up to 10 MB, arbitrary JSON; embedded images travel as-is), { "fileId": "…" } to reuse a JSON File already in the project, or an array of those for a many-file input. Martini stores each document as an immutable revision, freezes it into the run, and hands the Action a local copy; the canvas and the run record hold only its descriptor. A saved workflow may carry default documents; a run that names none uses them, and a required input with no default answers INVALID_FILE_INPUT.

variables pins a value for any variable for this run only. Keys are variable names (case-insensitive, as shown on the variable card) or ids; values are strings and replace the whole value. Unpinned variables keep their saved (or canvas) value. Only inputs the workflow's Actions read are accepted; any other key answers 400 WORKFLOW_VARIABLE_NOT_FOUND or WORKFLOW_BIN_NOT_FOUND with the accepted inputs listed under inputs. The run echoes what it pinned under variables and bins on every status read. Limits: 20,000 characters per variable and 100,000 in total; 20 bins with 200 assets each.

Every workflow and run carries a fingerprint: a hash of the machinery (each Action's brief, references, output bins, agent, pinned settings, and gate, plus the wired bins), never of names, bin contents, or variable values. Ids stay stable when a workflow is edited; the fingerprint changes. Pass the one you read to POST /v1/workflows/{workflowId}/runs and a changed workflow answers 409 WORKFLOW_CHANGED with the current fingerprint instead of running something else. Omit it to run whatever the workflow is now.

oliveBudget is optional. When omitted, the run records budgetSource: "auto" and Martini arms the spend rail at each Action's gate from that Action's estimate, raising it for a costlier later Action rather than failing. When supplied, a plan estimated over the budget fails the run with the estimate in error; raise the budget and run again. Both generation and agent spend are reported in olives as the run progresses.

Errors are JSON { "error": "<copy for a human>", "code": "<STABLE_CODE>" }. Branch on code; the copy may change.

@martini-film/client 0.10.0 and later (JavaScript, TypeScript) and martini-client 0.3.0 and later (Python) wrap every call. Martini-native routes reject with MartiniApiError, which carries status, the stable code, and the parsed body; the Python client raises a MartiniAPIError subclass per status (ConflictError, RateLimitError, …) with the same fields.

For any other language, the complete /v1 surface is described by an OpenAPI 3.1 document at api.martini.film/v1/openapi.json (no authentication) — point a client generator or a coding agent at it.

workflows.subscribe() and runs.wait() poll with jittered backoff from 2 seconds up to 15 seconds and give up after 30 minutes by default; pass pollInterval and timeoutMs (poll_interval and timeout in Python) to change that. Both return a failed or cancelled run rather than throwing; check status. Use Node.js 18 or later or Python 3.10 or later, and call Martini from trusted server code only.

• Webhooks when a run settles. Poll the status endpoint for now.
• Bins as an identity on the wire (what each bin holds so far on the run, the bin name on each result). Group takes by actionId for now.
• Authoring or editing a workflow over this API. Build it on a canvas in Martini, or via MCP.
• Notes and directly tagged assets as per-run inputs. Only variables and input bins can be pinned.
• Deleting a run or its canvas. Runs stay in the Workflow runs project until you remove them in the app.