Create and trigger a workflow run

post

https://api2.pennsieve.io/compute/workflows/runs

Primary endpoint: create + trigger a run. Provide either workflowInstanceId
(existing config) or workflowInstanceConfiguration (find-or-create config).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Run request payload

workflowInstanceId

string

UUID of an existing workflow instance config (mode 1)

workflowInstanceConfiguration

object

Inline config for find-or-create (mode 2)

name

string

Optional human-friendly label for the run. When omitted, workflow-service generates a default of "run-

app

object

Makes this an app run: a one-off run of one App Store app version with no stored workflow ("Try this app"). The run is the one-step workflow GET /apps/run-definition returns (its inputs are the app's input ports; one output takes everything to a download). workflowInstanceConfiguration then names only computeNodeId (and processorConfigs), no workflowId; dataSources must bind at least one input.

tenant

string

Who the run is for: ORG#{uuid} for a workspace the caller belongs to, or USER#{uuid} for the caller (My Workspace). Decides where the run is listed, who may read it and whose counters its cost is attributed to; not who pays, which is the compute node's account, nor the spend caps, which are the node's and the caller's. Declaring another user, or a workspace the caller is not a member of, is refused. When omitted the run takes the compute node's tenant, as runs did before this field; clients should send it.

datasetId

string

dataSources

object

Structured data-source inputs keyed by data-source node ID. Each entry must match a data-source node in the workflow definition.

dataTargets

object

Per-data-target inputs keyed by data-target node ID. The user provides per-run values (e.g. folder). The system enriches each entry with registry params (e.g. uploadBucket).

processorParams

object

Per-processor runtime parameters keyed by processor node ID.

tags

object

Per-run image tag/version overrides keyed by processor node ID. Applied to a copy of the workflow's DAG snapshot before the run is persisted; the source workflow definition is not mutated. Useful for pinning a specific version for one run, or supplying a tag for legacy workflow snapshots that predate the tag requirement.

layers

array of strings

deprecated

Retired. Compute-node layers were replaced by environments and reference data; a request with any layers is refused with 400.

layers

completionCallbackUrl

string

Optional. When set, workflow-service POSTs a webhook to this URL on terminal status (SUCCEEDED | FAILED | CANCELED) so the triggering caller can react to completion without polling. v1 contract: must be a Lambda Function URL with AWS_IAM auth; workflow-service signs the POST with SigV4 using its execution role. Generic by design — any service, UI, or processor that triggers a run can register a hook.

completionCallbackContext

object

Optional, opaque to workflow-service. Whatever the caller stashes here is echoed back verbatim in the webhook body on terminal status. Typical contents: a WebSocket connection ID, a conversation/correlation ID, an originating request UUID — anything the caller needs to route the completion event.

maxCostUsd

double

Optional per-execution LLM cost cap (USD). When set, workflow-service forwards it to compute-gateway-v2 on the workflow-init request body; compute-gateway-v2 persists it on the Step Functions input; the llm-governor-proxy sidecar attached to each processor task enforces it as executionBudgetUsd on every Bedrock call made during the run.
Zero/omitted means no caller-side cap (the governor still enforces its own per-node ceilings independently). chat-service populates this when a workflow is triggered through an MCP tool, derived from the user's resolved per-user-per-node quota.

Responses

503

Spend limits or recorded spend could not be read, so the run was
denied. The gate fails closed: on a shared compute node it is the
only control between open access and the AWS bill.

Language

Credentials

Header

URL

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

200The run was successfully triggered

400Bad request: among others, a processorConfigs variant the step's app version doesn't have, or one on a node that isn't a processor step; a compute type the step's variant doesn't support; a GPU step on a node without GPUs (maxGpuInstances=0).

402Pipeline spend cap reached on this compute node. Distinct from 403 so the caller can tell "you cannot use this node" apart from "you have used up this period's allowance".

403Forbidden. Possible reasons: user lacks access to compute node, or workflow contains processor source URLs not in the compute node's allowed processors whitelist.

4XXIncorrect authentication or user has incorrect permissions.

5XXServer Error