> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uselamina.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Apps And Executions

> The core Lamina mental model: discover an app, inspect its inputs, run it asynchronously, then fetch the execution result.

## The Core Lamina Model

### App

An **app** is a packaged workflow with a stable input contract.

Think of an app as the unit you expose in your product. One app might generate product imagery, another might run try-on, and another might turn still assets into video. The integration pattern stays the same.

You use app endpoints to:

* discover what is available
* inspect the app's parameters
* optionally inspect the underlying workflow graph
* start an execution

### Execution

An **execution** is one asynchronous run of an app.

Executions are durable server-side jobs. They may complete quickly for lightweight image tasks, or take longer for multi-step catalog and video workflows.

## Standard Flow

<Steps>
  <Step title="Discover apps">
    Call `GET /v1/apps` to find an app you can run.
  </Step>

  <Step title="Inspect parameters">
    Call `GET /v1/apps/{appId}` to see which inputs the app accepts.
  </Step>

  <Step title="Start execution">
    Call `POST /v1/apps/{appId}/runs?webhook=<your_url>` with your inputs.
  </Step>

  <Step title="Get results">
    Receive results via webhook callback, or poll `GET /v1/runs/{runId}` until the status is terminal.
  </Step>
</Steps>

The point of this model is stability: your backend always works with `appId`, `runId`, `inputs`, and `outputs`, even as the workflows behind those apps evolve.

## Execution Lifecycle

Executions move through a small set of top-level states:

* `queued`
* `running`
* `completed`
* `failed`

For long-running apps, especially video generation, the request that starts execution returns quickly. Your integration should either pass a `?webhook=` URL to receive results automatically, or treat the execution ID as a job handle and poll for status.

## What Comes Back

When you first start an execution, Lamina may return placeholder outputs with status `pending`.

When the execution finishes:

* output `type` changes from `pending` to something like `image`, `video`, or `text`
* `value` contains the final result
* `status` becomes `completed` for successful outputs

If execution fails, inspect:

* the top-level `errorMessage`
* each output's `error` field

## When To Use Workflow Inspection

`GET /v1/apps/{appId}/workflow` returns the node graph behind an app.

Most product integrations do not need this endpoint. It is useful when you want to:

* reason about what the app does internally
* build richer agent tooling
* classify apps by pipeline structure

For most backend and product teams, the core API surface is still:

* list apps
* get app
* run app
* get execution