> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API overview

> Drive Melius canvases and generations programmatically over a REST API.

The Melius REST API drives Melius canvases and generations from your own code — create projects and canvases, add nodes, wire edges, run generations across the latest image, video, audio, and language models, and read the results. It runs on the same backend as the Melius web app, CLI, and MCP server.

<Info>
  You authenticate with an API key. Create one in the Melius app under **Team settings → Integrations**. See [Authentication](/api/authentication).
</Info>

## Base URL

```
https://api.melius.com/api/v1
```

Every request needs a bearer API key. You can optionally select which team to act on with the `x-team-id` header — it defaults to the team your key belongs to:

```bash theme={null}
Authorization: Bearer mel_...
x-team-id: <your team id>   # optional
```

## How generations work

A generation in Melius **is a canvas node** — there's no separate "generate" path, so the API stays consistent with the app. You create a node, start a run, and poll the run until it finishes:

```
POST /projects                          → create a project
POST /projects/:projectId/canvases      → create a canvas
POST /canvases/:canvasId/direct/nodes   → add a node (prompt + optional model)
POST /nodes/:nodeId/runs                → start a run
GET  /node-runs/:nodeRunId  (poll)      → status: running → finished
```

Runs are **asynchronous jobs**. Starting a run returns immediately with a run id; the generation runs in the background across Melius's model providers. Poll the run until `status` is `finished` (or `failed`).

## Get the result

When a run finishes, fetch the URL of the generated file with one more call:

```bash theme={null}
POST /api/v1/node-runs/:nodeRunId/download   → { "url": "...", "filename": "...", "size": 1234 }
```

## Rate limits and credits

* **Credits.** Generations consume credits from the team you act on, exactly like the app. The credit cost of each model is shown in `GET /generation/models`.
* **Rate limits.** API requests are subject to a monthly per-plan request limit. When you exceed it, requests return `429` with a `Retry-After` header. Enterprise plans are unlimited.

## Next steps

<Columns cols={2}>
  <Card title="Quickstart" icon="rocket" href="/api/quickstart">
    Create a key and run your first generation end to end.
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    API keys, the `x-team-id` header, and how keys are scoped.
  </Card>
</Columns>

Browse every endpoint under **API reference** in the sidebar — each has a live **try it** playground and code samples in cURL, Python, TypeScript, PHP, Go, and Ruby.