Skip to main content
POST
Run App
Start an execution of a specific app. You choose the app and provide exact inputs. For automatic app selection, use POST /v1/content/create instead. Key each field in inputs by the parameter’s key (stable snake_case identifier) or name from GET /v1/apps/{appId}. Prefer key when present — it never changes, while name is a display label and matches case-sensitively.

On-brand runs

Set applyBrand: true to make the output on-brand without hand-writing brand into every input. Lamina folds the workspace’s brand negatives and visual style onto the app’s visual generation nodes before the run. Anything you pass in inputs still wins — brand only fills fields you left unset, and never touches a field the app exposes as a parameter. Pass brandProfileId to target a specific brand in a multi-brand workspace; omit it for the workspace’s active brand.

Sandbox / test mode

Build and CI your integration without spending credits. Send the header X-Lamina-Test: true (or "test": true in the body) on a run or on POST /v1/workflows/generate. Lamina validates the request exactly as it would for real — bad inputs still return 400 — then returns a deterministic stub (status: "test", a test_… id) without dispatching an execution, calling any model, or charging credits. Point your tests at it to exercise your request-building and response-handling for free, then drop the header to go live.

Getting results

Authorizations

x-api-key
string
header
required

Workspace API key. Prefix: lma_. Example: lma_abc123...

Path Parameters

appId
string<uuid>
required

The app ID (UUID) from the List Apps response

Query Parameters

webhook
string<uri>

URL to receive execution results when complete. We POST the same payload as the polling endpoint, signed with ED25519. Must be https or http.

Body

application/json
inputs
object
required

Parameter values keyed by parameter name (from the Get App response). Keys are case-sensitive and must match exactly.

Example:
inputOverrides
object

Advanced: per-node input overrides keyed by node id, set on specific workflow nodes directly (bypassing parameter-name mapping). Most callers use inputs.

applyBrand
boolean
default:false

Fold the workspace's brand (negatives + visual style) onto the app's visual generation nodes so output is on-brand, without hand-writing brand into inputs. Layered below your inputs, which always win.

brandProfileId
string

Target a specific brand profile when applyBrand is set. Omit to use the workspace active brand.

test
boolean
default:false

Sandbox mode (or send header X-Lamina-Test: true): validate inputs and return a deterministic stub run -- no execution is dispatched and no credits are charged.

Response

Run started. Poll GET /v1/runs/{runId} or stream via SSE for results.

data
object

Returned when execution starts. All output values are null initially.