> ## 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.

# Inputs And Outputs

> How Lamina parameter types map to request payloads, and how to interpret execution outputs.

## Building Requests Safely

When starting an execution, send an `inputs` object keyed by parameter **name** from `GET /v1/apps/{appId}`.

Parameter names are case-sensitive and must match the app metadata exactly.

This is what lets Lamina support different apps without changing the request envelope. Your code keeps sending `inputs`; only the parameter schema changes from app to app.

Example:

```json theme={null}
{
  "inputs": {
    "Front": "https://example.com/front.jpg",
    "Back": "https://example.com/back.jpg",
    "Model Gender": "Female"
  }
}
```

## Public Parameter Types

| Type      | What you send   | Notes                                        |
| --------- | --------------- | -------------------------------------------- |
| `text`    | a string        | prompts, descriptions, product names         |
| `options` | an option label | send the displayed label, not an internal ID |
| `url`     | a public URL    | typically an image or video URL              |

## Important Rules

### `options`

For option parameters, send the **label** shown in the app metadata.

Example:

```json theme={null}
{
  "inputs": {
    "Location": "Studio"
  }
}
```

### `url`

URLs should be publicly accessible by Lamina at execution time.

Good sources include:

* your own CDN
* cloud object storage with public access
* signed URLs that will remain valid long enough for processing

If you use signed URLs, make sure they stay valid for the full processing window.

### Defaults

Every parameter is returned with `required: true`. If it has a `default`, omitting it is safe — the app uses the default value. If it has no `default`, you must supply a value or the request is rejected with a `missing_no_default` error.

## Reading Results

Executions return an `outputs` array. Each output object contains:

* `id`
* `label`
* `type`
* `value`
* `status`
* `error`

Example completed output:

```json theme={null}
{
  "id": "node-1",
  "label": "Generated Video",
  "type": "video",
  "value": "https://cdn.example.com/result.mp4",
  "status": "completed",
  "error": null
}
```

## Output Types

Common output types include:

* `image`
* `video`
* `text`
* `pending`

**Branch on `status`, not `type`, to decide if an output is finished.** `type` stays `"pending"` on failed outputs — only `status` flips to `"error"`. At execution start, outputs appear with `type: "pending"` and `value: null`; treat those as placeholders until `status` reaches `completed`, `error`, or `cancelled`.

## Agent Artifacts

Agent-facing status responses also include an `artifacts` array. `outputs` remains the backward-compatible raw result list, while `artifacts` adds reuse metadata so agents can chain creative work safely.

Each artifact includes:

* `id`, `label`, `type`, `status`, and `error`
* `url` when the artifact is downloadable media
* `mimeType`, `dimensions`, and `durationSeconds` when known or inferable
* `provider`, `model`, `cost`, and `prompt` when available
* `reusableAs` roles such as `image_reference` or `video_reference`
* `provenance` with `runId`, `workflowId`, node identity, and output index

Use `artifacts` when an agent needs to reuse, publish, inspect, or pass a result into another Lamina run. Use `outputs` for compatibility with existing integrations.

## Practical Integration Pattern

For admin tooling, merchant tooling, and agent-driven clients:

1. fetch the app metadata
2. render input controls from the parameter list
3. submit `inputs` keyed by parameter name
4. handle output rendering based on output type