---
title: "POST /v1/runs"
method: POST
path: "/v1/runs"
---

# POST /v1/runs

`POST /v1/runs`

Execute an inline workflow definition (ephemeral run). The definition must use "manual" trigger type. No workflow is saved — the definition is executed once and the run is recorded with workflowId="". Requires WorkflowCreate permission.

## Request body

- EphemeralRunParams
  - `definition` GithubComB3FunB3MonoServicesB3osWorkflowInternalPkgEntityWorkflowDefinition, required — Definition is the full workflow graph to execute. Must contain a "root" node with type "manual". All action nodes referenced in children arrays must be present.
    - `inputSchema` GithubComB3FunB3MonoServicesB3osWorkflowInternalPkgEntityWorkflowInput[]
      - `description` string
      - `key` string
      - `required` boolean
      - `type` string — "string", "number", "boolean", "object", "array"
    - `nodes` object, required
    - `sensitivePropKeys` string[]
  - `payload` object — Payload is merged into the trigger result (root node output), accessible via {{root.result.key}} expressions. A "triggeredAt" timestamp is always added automatically.
  - `propValues` object — PropValues are template parameter values injected into the run context, accessible via {{$props.key}} expressions.
  - `runId` string — RunID is an optional client-generated run ID. Must start with "run_" prefix. If omitted, a run ID is generated server-side. Use this to subscribe to SSE stream before triggering the run.

## Response `200`

Run created and enqueued for execution

- RunSuccessResponse
  - `code` integer
  - `data` RunResponse
    - `runId` string
  - `message` string
  - `requestId` string

## Other responses

- `400` — Invalid definition (400228), non-manual trigger (400229), invalid run ID (400078), or duplicate run ID (400079)
- `402` — Insufficient CU balance
- `403` — Missing org context or insufficient permissions

---

[API](https://skmtc.net/b3-fun/apis/b3os-workflow-api.md) · [All operations](https://skmtc.net/b3-fun/apis/b3os-workflow-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/b3-fun/b3os-workflow-api/versions/5a750a5a9596/schema)