Workflows API

Run a workflow you built in the Studio with one request.

Beta A workflow is a graph of nodes: built-in intelligence nodes, your custom nodes, and deterministic utility nodes (input, output, map, condition). You build and test it in the Studio, publish an immutable version, and call it here. Workflows are the only way to deploy what you build: nodes are reusable components inside them.

One node, one API

To deploy a single node, build Input → node → Output in the Studio, or choose Create Workflow on a built-in node's page in the console. The workflow accepts exactly the node's input and returns exactly its output, with no mapping to set up. A single-node workflow costs one evaluation per successful call, the same as the node; the workflow itself is never billed.

Request

POST /v1/workflows/{workflow_id}/execute

curl https://kovca.io/api/v1/workflows/wf_.../execute \
  -H "Authorization: Bearer $KOVCA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f0e-4a51-4f53-9e7d-1b5f0f6d2c11" \
  -d '{ "input": { "message": "My order arrived broken." }, "version": 3 }'

Field	Type	Description
input	object	Validated against the workflow's input fields before anything runs. Unknown fields are rejected.
version	integer (optional)	A published version. Omit it to run the latest published version. Drafts can't be called through the API.

The Idempotency-Key header is optional and recommended for retries. See Idempotency.

Response

200 OK

{
  "request_id": "req_...",
  "run_id": "run_...",
  "workflow": { "id": "wf_...", "version": 3 },
  "status": "succeeded",
  "output": { "priority": "high", "escalate": true },
  "steps": [
    { "id": "input", "status": "succeeded" },
    { "id": "triage", "status": "succeeded" },
    { "id": "check", "status": "succeeded" },
    { "id": "policy", "status": "skipped", "reason": "branch_not_taken" },
    { "id": "output", "status": "succeeded" }
  ],
  "evaluations": 1
}

Field	Type	Description
run_id	string	Look up the run's metadata later with the Runs API.
output	object	Built by the output node. A value from a step that didn't run is null; Kovca never invents one.
steps	array	Every node with its status: succeeded, failed, skipped (branch_not_taken or source_skipped), or not_run.
evaluations	integer	Successful intelligence steps in this run. This is what you're billed for.

Logic nodes

Deterministic nodes are free: they never call a model and never count as evaluations.

Condition: rules on values (equals, one of, greater than, true, present, …); continues on true or false.
Switch: routes on one value to the first matching case, or default.
Merge: joins branches back together.
Map: builds an object from references and fixed values.
Calculate: exact decimal add, subtract, multiply, divide, min, max, abs, and round. A missing or non-numeric value gives null.
Text: fills a template like Order {{input.order_id}} is {{nodes.triage.output.status}}.
Lookup: maps a value through a table you define, with a fallback.
List: count, first, last, join, sum, contains, or unique.
Stop: rejects the request with your message.

How a run executes

A node runs when all of its predecessors have settled, at least one incoming connection is active, and every value it maps succeeded.
Independent intelligence steps run in parallel, up to 4 at a time.
Condition nodes activate only their true or false branch, and switch nodes only the branch of the matching case (or default); nodes reachable only through another branch are skipped.
A merge node runs when any of its incoming branches ran, taking each field from the first source that has a value.
A stop node ends the run with 422 UNPROCESSABLE_CONTENT and the message you configured. Evaluations that already succeeded are billed.
On the first failure, no new steps start. Steps already running finish; if they succeed they're billed but their outputs are discarded. The run fails with the error of the failed step.
A run has 30 seconds. After that it fails with TIMEOUT and later step results are ignored and not billed.

Errors

Errors use the standard envelope, plus run_id, evaluations (steps that already succeeded and are billed), failed_step, and the steps list when the run started. See error codes.

A step failed

{
  "error": { "code": "SERVICE_UNAVAILABLE", "message": "..." },
  "request_id": "req_...",
  "run_id": "run_...",
  "evaluations": 1,
  "failed_step": "policy",
  "workflow": { "id": "wf_...", "version": 3 },
  "steps": [ ... ]
}

Limits

Request bodies up to 16 KB; each step's input up to 16 KB.
Up to 25 nodes, 8 intelligence nodes, 8 conditions, and 50 connections per workflow.
A workflow call counts as one request toward your requests-per-minute limit. Evaluations have their own per-minute limit: 30 on Free and 240 on Pay As You Go. Exceeding either returns 429 RATE_LIMITED.
Before a run starts, Kovca reserves the evaluations it will certainly need. If your allowance or spending cap can't cover them, the request is refused and nothing runs.

Privacy

Kovca stores run metadata (status, timings, step statuses, evaluation counts) for 30 days. Inputs and outputs are never stored.