# Lamina for Agents

> The creative API for AI agents and apps. Pass a brief and a brand kit; get a full campaign back. Available as a REST API, a TypeScript and Python SDK, a CLI, and a hosted MCP server that any agent client (Claude, Cursor, Windsurf, VS Code, Zed) can call directly.

Canonical page: https://uselamina.ai/agents

## What you get

- **One creative API** instead of stitching together image, video, try-on, and editing models.
- **Typed JSON responses**, schema-validated end to end. Safe for agent parsing.
- **Idempotent runs** — retries are free.
- **SSE streaming** of phase and progress for every long-running run.
- **Deterministic** — same brief + brand + seed produces the same output.
- **Brand grounding** — every output respects palette, voice, and rules from the brand kit.
- **App generation** — turn a plain-English instruction into a runnable app.

## Integration paths

1. **Hosted MCP (recommended)** — connect the task-level v2 front door with `npx add-mcp https://app.uselamina.ai/mcp/agent/v2` (OAuth on connect, no API key). Stdio-only clients bridge via `npx -y mcp-remote https://app.uselamina.ai/mcp/agent/v2`. The old self-hosted `@uselamina/mcp` package is retired.
2. **REST API** — `https://app.uselamina.ai/v1`. Auth via `x-api-key: lma_...` (or `Authorization: Bearer <key>`).
3. **SDK** — `@uselamina/sdk` (TypeScript) and a Python SDK. Typed responses.
4. **CLI** — `@uselamina/cli`. `lamina login`, `lamina content plan`, `lamina run`; `--json` on every command.

## Install the agent skill

Drop a Lamina skill into your coding agent with `npx @uselamina/skill` — it teaches the plan → approval → execute → deliver lifecycle.

## Quickstart

```bash
# Connect the hosted v2 MCP (OAuth on connect, no API key)
npx add-mcp https://app.uselamina.ai/mcp/agent/v2

# Stdio-only clients bridge the same endpoint:
npx -y mcp-remote https://app.uselamina.ai/mcp/agent/v2
```

## Recommended endpoint: v2 (7 task-level tools)

Hosted at `https://app.uselamina.ai/mcp/agent/v2`. This is the recommended front door. The lifecycle is:

`credits / brand context → plan → clarify → show frozen plan + cost → explicit approval → execute within maxCredits → status → deliver`

The exactly-7 tools (snake_case):

- `lamina_credits` — check the workspace credit balance before planning.
- `lamina_brand_context` — load the active brand's palette, voice, and rules to ground the plan.
- `lamina_plan` — turn a brief into a frozen, step-by-step plan with an estimated credit cost. **Planning does not dispatch generation.**
- `lamina_execute` — run an approved plan. Takes the plan fingerprint, a `maxCredits` ceiling (a finite spend cap), and an idempotency key.
- `lamina_status` — poll a run until terminal. Each call waits up to ~25 seconds; on `timedOut: true`, call again. Finished assets are at `outputs[].url`.
- `lamina_cancel` — request cancellation of an in-flight run; returns the truthful cancellation state (e.g. `cancelling`, `cancelled`, or `already terminal`).
- `lamina_upload_asset` — upload a reference file; returns a URL for plan and run inputs.

Planning is free and side-effect-free; only `lamina_execute` spends credits, and never beyond `maxCredits`.

## Advanced endpoint (30-tool)

Hosted at `https://app.uselamina.ai/mcp/agent`. This is the **optional** 30-tool advanced surface for direct app/model/compose control, brand or app mutations, refinement, and checkout. On this surface, advanced `lamina_create` is **plan-only** (it does not run work); `lamina_run` dispatches the selected app. Prefer the v2 endpoint above unless you need low-level control.

The v2 request URL and the advanced URL share the parent OAuth resource `https://app.uselamina.ai/mcp/agent`.

See the canonical advanced tool reference and agent recipes at https://docs.uselamina.ai/agents rather than duplicating all 30 tool descriptions here.

## REST endpoints (selected)

Base: `https://app.uselamina.ai/v1`. Auth: `x-api-key: lma_...`.

- `POST /v1/content/create` — create from a brief. Returns a run.
- `POST /v1/apps/{appId}/runs` — run a specific app with explicit inputs.
- `GET /v1/runs/{runId}` — poll run status and outputs.
- `POST /v1/content/score` — score outputs against the brand kit.
- `POST /v1/publishing/publish` — deliver to connected channels.
- `POST /v1/workflows/generate` — generate a runnable app from an instruction (accepts `visibility`).
- `POST /v1/apps/{appId}/visibility` — set an app `private | shared | public`.

## Agent integration patterns (v2)

- **Plan, approve, execute**: `lamina_credits` / `lamina_brand_context` → `lamina_plan` → show the frozen plan + cost and get explicit approval → `lamina_execute` (with `maxCredits` and an idempotency key) → `lamina_status` until terminal.
- **Poll correctly**: `lamina_status` returns after ~25s; on `timedOut: true` call it again until you reach a terminal state, then read `outputs[].url`.
- **Cancel safely**: call `lamina_cancel` for an in-flight run and trust the returned state — a terminal run cannot be cancelled.

## Supported MCP clients

Claude (desktop and Claude Code), Cursor, Windsurf, VS Code, Zed, and any MCP-compatible client. Non-MCP automation tools (Raycast, n8n, Zapier) integrate via the REST API.

## Open source

- GitHub org: https://github.com/uselamina
- SDK: https://github.com/uselamina/sdk
- CLI: https://github.com/uselamina/lamina-cli

## Pricing

Per-credit pricing. Credits are consumed by job type (a packshot costs less than a 9:16 reel). See https://uselamina.ai/pricing.

## Trust & security

- SOC 2 posture and sub-processor disclosure: https://uselamina.ai/security and https://uselamina.ai/sub-processors.
- Customer assets are not used to train third-party foundation models.
- Brand kits and outputs are tenant-isolated.

## Related

- [HTML page](https://uselamina.ai/agents)
- [llms.txt](https://uselamina.ai/llms.txt)
- [llms-full.txt](https://uselamina.ai/llms-full.txt)
- [Pricing](https://uselamina.ai/pricing) · [Apps](https://uselamina.ai/apps) · [FAQ](https://uselamina.ai/faq)