Skip to main content

​
The Two Main Objects

​
App

An app is a runnable workflow with a stable input contract. 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 or may take much longer for heavy image/video workflows.

​
Typical Flow

1

Discover apps

Call GET /v1/apps to find an app you can run.
2

Inspect parameters

Call GET /v1/apps/{appId} to see which inputs the app accepts.
3

Start execution

Call POST /v1/apps/{appId}/executions?webhook=<your_url> with your inputs.
4

Get results

Receive results via webhook callback, or poll GET /v1/executions/{executionId} until the status is terminal.

​
Execution Status 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.

​
Outputs

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

​
Workflow Visibility

GET /v1/apps/{appId}/workflow returns the node graph behind an app. This is useful if you want to:
  • reason about what the app does internally
  • build richer agent tooling
  • classify apps by pipeline structure
Not every integration needs this endpoint. Most integrations only need:
  • list apps
  • get app
  • run app
  • get execution