---
title: "Run an app"
method: POST
path: "/apps/{appId}/runs"
tags: ["Runs"]
---

# Run an app

`POST /apps/{appId}/runs`

## Request

- Base URL: `https://app.uselamina.ai/v1`
- URL: `https://app.uselamina.ai/v1/apps/{appId}/runs`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Start a new run of an app with the given inputs. Returns immediately with run ID; poll GET /runs/{id} or use SSE streaming for results.

## Path parameters

- `appId` string, uuid, required

## Query parameters

- `webhook` string, uri

## Request body

- object
  - `inputs` object: Input values keyed by parameter name or ID
  - `inputOverrides` object: Per-node input overrides
  - `applyBrand` boolean: 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: 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 `202`

Execution started

- object
  - `data` object, required
    - `runId` string, uuid, required
    - `workflowId` string, uuid, required
    - `workflowName` string
    - `status` string, required
    - `webhookUrl` string, nullable
    - `outputs` ExecutionOutput[]
      - `id` string, required
      - `label` string, required
      - `type` string, required
      - `value` unknown
      - `status` string, required
      - `error` string, nullable
      - `mimeType` string: Canonical MIME type (e.g. "image/png", "video/mp4"). Present on completed outputs.
      - `contentDescription` string, nullable: What was produced (e.g. "AI-generated photograph"). Present on completed outputs.
      - `compatibleInputTypes` string[]: Downstream tool categories this output can feed into. Present on completed outputs.
      - `suggestedNextSteps` union[]: Actionable hints for chaining. Each item is either a plain string or an object with description and toolHint. Present on completed outputs.
        - union
          - string
          - SuggestedNextStep
            - `description` string, required: Human-readable next step description
            - `toolHint` string, nullable, required: Lamina tool name to invoke (e.g. "run_app", "lamina_create", "publish_content")
      - `canChainAs` string[]: Semantic roles this output can play in a pipeline (e.g. "hero_image", "social_clip"). Present on completed outputs.
      - `platformsOptimized` string[]: Platforms the output is likely formatted for (e.g. "instagram", "tiktok"). Present on completed outputs.
      - `dimensions` object, nullable: Output dimensions in pixels. Present on completed outputs when metadata is available.
        - `width` integer, required: Width in pixels
        - `height` integer, required: Height in pixels
      - `durationSeconds` number, nullable: Duration in seconds. Present on completed video/audio outputs when metadata is available.

## Other responses

- `400`: Validation error
- `401`: Missing or invalid API key
- `500`: Internal server error

---

[API](https://skmtc.dev/uselamina/apis/lamina-v1-api.md) · [All operations](https://skmtc.dev/uselamina/apis/lamina-v1-api/llms.txt) · [OpenAPI document](https://skmtc.dev/uselamina/apis/lamina-v1-api/revisions/73b598526531?raw)