Skip to main content

​
The Right Mental Model

Lamina apps are not single-shot utility functions. An agent should treat Lamina as a system with:
  • discoverable app capabilities
  • explicit input contracts
  • asynchronous execution
  • webhook-based or polling-based result delivery
  • typed outputs
The best integrations do not guess app inputs from app names alone. They inspect the app first, then execute.
1

Discover candidate apps

Use GET /api/apps to identify relevant apps by name and description.
2

Inspect the chosen app

Use GET /api/apps/{appId} before execution so the agent knows the exact parameter names and allowed option labels.
3

Construct inputs from app metadata

Build the inputs object using the returned parameter names exactly as provided.
4

Start execution with webhook

Call POST /api/apps/{appId}/executions?webhook=<your_url> and store the returned executionId.
5

Receive results

Your webhook endpoint receives the completed results. Or poll GET /api/executions/{executionId} as a fallback.

​
Always Inspect Parameters First

Before executing an app, an agent should fetch app metadata unless it already has fresh metadata cached for that exact appId. This is important because the app metadata is the source of truth for:
  • parameter names
  • whether fields are required
  • valid options labels
  • whether a field expects a media URL

​
Use Parameter Names Exactly

When calling POST /api/apps/{appId}/executions, inputs should be keyed by parameter name. Example: 
{
  "inputs": {
    "Front": "https://example.com/front.jpg",
    "Location": "Studio"
  }
}
Do not invent aliases or normalize parameter names unless your integration keeps a reliable mapping layer.

​
Handle options Carefully

For parameters of type options, send one of the labels returned by the app metadata. If the app says the valid options are: 
["Male", "Female"]
then the execution request should send one of those exact labels.

​
Use Webhooks For Production

For production agent integrations, always use webhooks instead of polling: 
POST /api/apps/{appId}/executions?webhook=https://your-agent.com/lamina-callback
Benefits over polling:
  • No polling loop to manage
  • Results arrive immediately when ready
  • Signed with ED25519 — verify authenticity
  • Automatic retries if your endpoint is temporarily down

​
Webhook Payload Structure

The webhook payload matches the polling response exactly: 
{
  "data": {
    "executionId": "...",
    "workflowId": "...",
    "status": "completed",
    "outputs": [
      { "id": "...", "label": "Generated Image", "type": "image", "value": "https://...", "status": "completed", "error": null }
    ],
    "errorMessage": null,
    "startedAt": "...",
    "completedAt": "...",
    "createdAt": "..."
  }
}

​
Read Output Type Before Consuming Value

Do not assume every output is an image URL. Check:
  • type
  • status
  • value
Examples of output types include:
  • image
  • video
  • text
  • pending

​
Handle Failures Explicitly

If execution fails:
  • inspect top-level errorMessage
  • inspect each output’s error
  • avoid blindly retrying the same invalid inputs
If the failure is caused by invalid inputs, fetch the app metadata again and rebuild the request payload.

​
Good Agent Behaviors

  • discover before execute
  • cache app metadata briefly, but refresh when uncertain
  • use webhooks for result delivery
  • preserve executionId for later retrieval
  • branch logic on output type
  • verify webhook signatures
  • surface execution failure with the returned error details

​
Poor Agent Behaviors

  • guessing parameter names from natural language
  • sending internal option IDs that were never returned by the API
  • treating execution as synchronous
  • resubmitting the same long-running request repeatedly because output is not immediate
  • ignoring webhook signatures