Skip to main content

​
Lamina API — Quick Start

Base URL: https://app.uselamina.ai Auth header: x-api-key: lma_your_api_key This guide assumes you already created a workspace API key in Lamina. This is the canonical Lamina flow:
  1. discover an app
  2. inspect its parameters
  3. start an execution
  4. receive results by webhook or polling

​
1. Discover an app

curl -H "x-api-key: lma_your_api_key" \
  https://app.uselamina.ai/v1/apps
Use search when you know the capability you want: 
curl -H "x-api-key: lma_your_api_key" \
  "https://app.uselamina.ai/v1/apps?search=catalog"
Pick an appId from the response.

​
2. Inspect the input schema

curl -H "x-api-key: lma_your_api_key" \
  https://app.uselamina.ai/v1/apps/{appId}

{
  "data": {
    "appId": "{appId}",
    "name": "Example Catalog App",
    "description": "Generate catalog images from product inputs",
    "parameters": [
      {
        "id": "front-image",
        "name": "Front",
        "type": "url",
        "required": true,
        "accept": ["image"]
      },
      {
        "id": "location",
        "name": "Location",
        "type": "options",
        "required": false,
        "options": ["Studio", "Urban", "Park"],
        "default": "Studio"
      },
      {
        "id": "prompt",
        "name": "Prompt",
        "type": "text",
        "required": false
      }
    ]
  }
}
Use the parameter name as the key when sending inputs. For options, send the label from the options array.

​
3. Start execution

Optionally pass ?webhook=<url> to receive results pushed to your server when complete. You can still poll the execution status regardless — webhooks and polling work side by side. 
curl -X POST \
  -H "x-api-key: lma_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "Front": "https://example.com/front.jpg",
      "Location": "Studio"
    }
  }' \
  "https://app.uselamina.ai/v1/apps/{appId}/executions?webhook=https://your-server.com/callback"

{
  "data": {
    "executionId": "<execution-id>",
    "workflowId": "{appId}",
    "workflowName": "Example Catalog App",
    "status": "queued",
    "outputs": [
      { "id": "node-1", "label": "Catalog Output", "type": "pending", "value": null, "status": "pending", "error": null }
    ]
  }
}

​
4. Get results

Via webhook: If you passed ?webhook=, your callback URL receives a POST with the results when the execution completes. The payload has the same structure as the polling response below, signed with ED25519 headers for verification. Via polling: If not using webhooks, poll every 3-5 seconds: 
curl -H "x-api-key: lma_your_api_key" \
  https://app.uselamina.ai/v1/executions/<execution-id>
Status flow: queued → running → completed or failed When status is "completed", output type changes from "pending" to "image", "video", or "text", and value contains the result: 
{
  "data": {
    "executionId": "<execution-id>",
    "status": "completed",
    "outputs": [
      {
        "id": "node-1",
        "label": "AI Designer",
        "type": "image",
        "value": "https://storage.example.com/generated/catalog-image.png",
        "status": "completed",
        "error": null
      }
    ],
    "errorMessage": null,
    "startedAt": "2026-03-23T12:22:41.694Z",
    "completedAt": "2026-03-23T12:24:15.000Z",
    "createdAt": "2026-03-23T12:22:40.552Z"
  }
}
If status is "failed", check errorMessage and each output’s error field.

​
5. Discover other apps

curl -H "x-api-key: lma_your_api_key" \
  "https://app.uselamina.ai/v1/apps?search=try on"

curl -H "x-api-key: lma_your_api_key" \
  "https://app.uselamina.ai/v1/apps?search=video"
The execution flow stays the same across image, catalog, try-on, and video apps. Only the appId and parameter schema change.

​
Production Notes

  • prefer webhooks over tight polling loops for long-running image or video jobs
  • cache app metadata if you call the same app repeatedly
  • validate inputs against the latest GET /v1/apps/{appId} response before execution
  • use Capability Recipes when you want business-facing documentation for specific use cases