Workflows

Start a run

Run a saved workflow using its saved definition and presets on a fresh canvas, or a placed workflow in place using its canvas state. Omitted bins keep their defaults; explicit bins replace them. Only saved bins marked required need caller input. projectId selects the destination only; omit it to use Workflow runs. Do not choose a placed copy to recover a saved workflow’s presets. Pin variable values by name or the selected workflow’s own input ids. A bin entry may also be a public https:// URL, a data: URI, or { url, filename }: Martini imports those files before the run starts and answers 400 WORKFLOW_INPUT_FETCH_FAILED (naming the bin and URL) without starting the run when one cannot be fetched or processed. Answers 201 with the run; poll GET /v1/runs/{runId}, and fetch GET /v1/runs/{runId}/results for the outputs settled so far or once it settles. Runs started here auto-approve.

post/v1/workflows/{workflowId}/runs

Request

Base URL: https://api.martini.film
URL: https://api.martini.film/v1/workflows/{workflowId}/runs
Auth: HTTP bearer

Path parameters

workflowIdstring required

A saved or placed workflow id.

Request body

compileboolean

Fable only: build and dry-test scripts without generating media. Pass oliveBudget: 0. Run the compiled placed workflow afterwards, or save it as a new version for future saved-workflow runs.

oliveBudgetnumber

Cap on what this run may spend, in olives. An explicit engine: "fable" request defaults to 1,000 olives when omitted and returns DEFAULT_OLIVE_BUDGET_APPLIED in warnings.

idempotencyKeystring

Re-posting the same key with the same body returns the run the first call created.

namestring

For a saved workflow, names its new run canvas (default: '<workflow name> · <UTC date time>'), so parallel runs are told apart; the run keeps the workflow's name. For a placed workflow, names the run.

variablesobject

Values for the variables the workflow's Actions read, keyed by variable name (case-insensitive) or id.

inputsobject

JSON file inputs keyed by their stable input key. Use { json: value } or { fileId: id }.

binsobject

Optional replacements keyed by input-bin name (case-insensitive) or id. Omit a bin to use its saved preset (saved workflow) or current contents (placed workflow). A supplied array replaces that bin; [] explicitly empties a media bin. JSON file inputs still require files. Only saved bins marked required need caller input. JSON file inputs can use inputs or saved default files. Each entry is an asset id, or a file to import first: a public https:// URL (up to 50 MB), a base64 data: URI (10 MB image, 30 MB MP4, 15 MB MP3/WAV, decoded), or { url, filename } for either. File inputs are for saved workflows (a placed workflow takes asset ids); imports land in the key’s default project, and the run starts once every import has processed (up to 60 s), at most 20 per run. The whole request body is capped at 41 MB, so several large files are better passed as URLs or uploads. A failed import answers WORKFLOW_INPUT_FETCH_FAILED and starts nothing.

fingerprintstring

The fingerprint last read for this workflow; the run is refused with WORKFLOW_CHANGED when it no longer matches.

projectIdstring uuid

Destination only, for saved workflows: store the new execution canvas in this project. Omit to use Workflow runs. The saved workflow ID still selects the definition and presets; this field never selects a source workflow or adopts project contents.

engine'fable' | 'harness'

Which engine drives the run. Omitted: the saved workflow's pin, else Workflow Beta ("fable"), one autonomous session running the workflow's compiled scripts. "harness" is the classic per-Action engine, the only one that supports resume. A Beta run with no oliveBudget gets 1,000 olives and a DEFAULT_OLIVE_BUDGET_APPLIED warning.

Response

The run, pending.

compileboolean

True for a script build, which generates no media.

thenRunIdstring nullable

Present only when a build will automatically start execution. Null until handoff: keep polling this build, including after completed, until the execution id appears. Then poll /v1/runs/{thenRunId} for media results. Absent for build-only requests.

idstring required

fingerprintstring required

workflowIdstring

phasestring nullable required

What Martini is doing right now ("unit 3/7 · waiting on generations"), the line the app shows. Display copy, not parseable; null unless the run is running.

origin'ui' | 'chat' | 'mcp' | 'api' required

createdAtstring required

startedAtstring nullable required

completedAtstring nullable required

errorstring nullable required

errorCode'model_provider_unavailable' nullable required

Why a failed run failed, as a stable code to branch on; error carries the copy for a human. Null unless the run failed and Martini can name the cause. model_provider_unavailable: the AI model provider (Anthropic) kept failing or could not be reached, so the run stopped. The workflow and its inputs did not cause it: start the run again.

variablesobject required

binsobject required

openInMartinistring required

Changes

No recorded changes to this operation across all 1 revision of this API.