Skip to main content

Workflows via the API

Every workflow you build on the canvas is callable as an endpoint: send fresh inputs, the server runs the whole pipeline, and you read the outputs per node. It's the same runner the app uses for server-side runs, which is what keeps canvas behavior and API behavior in lockstep.

For exact parameters and response shapes, see the Workflows and Workflow runs reference pages.

Discover your pipelines​

GET /v1/workflows        # your saved workflows
GET /v1/workflows/:id    # one workflow, including its node graph

Fetch the workflow first and note the ids of its input nodes — those ids are the keys you'll pass inputs under.

Execute with custom inputs​

POST /v1/workflows/:id/execute
{
  "inputs": {
    "concept":      { "text": "Alpine trail-running capsule, cold dawn light" },
    "productPhoto": { "storageId": "…" }
  },
  "wait": false
}

The rules:

  • inputs is keyed by node id. prompt / generateText nodes take { "text": … }; imageInput / videoInput nodes take a committed { "storageId": … }.
  • Omitted nodes keep their saved values — override only what changes per run. A workflow saved with a good prompt and one swappable image node needs a single input.
  • wait: false returns a run id immediately; poll for completion. Setting wait: true holds the response until the run finishes — fine for short pipelines, but polling is safer for anything long.

:::note Runs execute server-side Runs execute on Corte's servers regardless of how they're started, so API and MCP runs behave exactly like runs from the app canvas. :::

Poll the run and read results​

GET /v1/workflows/:id/runs/:runId

The response carries the run status plus per-node results. nodeResults[nodeId].output.value holds each node's output — media URLs for generate nodes, strings for text nodes. Read your Output node's entry for the pipeline's final result, or any intermediate node if you want the in-between artifacts too.

Getting media in​

Two ways to turn a file into the storageId an input node needs:

  • From a URL (easiest for automation): POST /v1/uploads/import with { "url": "https://…", "filename": "hero.jpg" } — the server fetches and commits it in one call.
  • From local bytes — the 3-step flow:
    1. POST /v1/uploads/ticket → { storageId, uploadUrl }
    2. HTTP PUT the bytes to uploadUrl
    3. POST /v1/uploads/:storageId/commit

GET /v1/storage/usage reports what you're storing; DELETE /v1/storage/:id removes an asset (see Storage).

Costs​

A workflow run spends credits per node exactly as it would in the app — generation nodes at model rates, Generate Text (LLM) nodes by token usage. The run is billed to the key's account, or to the project owner's pool for project-billed work (Pooled billing). Runs fail fast with insufficient_credits (402) when the balance can't cover an estimate.