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

# Quickstart

> Make your first Magica REST API calls in under five minutes.

This guide verifies your API key, discovers a model, inspects its input schema, estimates credits, and starts a model run.

***

## 1. Get your API key

<Steps>
  <Step title="Sign in">
    Open [app.magica.com](https://app.magica.com) and sign in.
  </Step>

  <Step title="Open API Keys">Go to **Settings -> API Keys -> Manage**.</Step>

  <Step title="Create a key">
    Click **Create Key**, label it, and copy the full `gx_...` token
    immediately. It is only shown once.
  </Step>
</Steps>

<Tip>
  Store the key in an environment variable like `MAGICA_API_KEY`. Never paste it
  in committed code or screenshots.
</Tip>

See [Authentication](/authentication) for rate limits, key rotation, and revocation.

***

## 2. Base URL

```text theme={null}
https://api.magica.com/api
```

Every endpoint in this reference is relative to that base. The current REST version is `/v1`.

***

## 3. List models

Use a read-only call to verify the key and discover model identifiers.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.magica.com/api/v1/models \
      -H "Authorization: Bearer $MAGICA_API_KEY"
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const res = await fetch("https://api.magica.com/api/v1/models", {
      headers: { Authorization: `Bearer ${process.env.MAGICA_API_KEY}` },
    });
    const models = await res.json();
    console.log(models.map((model) => model.nodeType));
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import os, requests

    res = requests.get(
        "https://api.magica.com/api/v1/models",
        headers={"Authorization": f"Bearer {os.environ['MAGICA_API_KEY']}"},
    )
    print([model["nodeType"] for model in res.json()])
    ```
  </Tab>
</Tabs>

A `401 Unauthorized` here means the key is missing, malformed, revoked, or expired.

***

## 4. Inspect model schema

Pick a `modelId` from `subModels[].subModelId`, or use `nodeType` for a single-mode model.

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl https://api.magica.com/api/v1/models/flux-2-max-text/schema \
      -H "Authorization: Bearer $MAGICA_API_KEY"
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const modelId = "flux-2-max-text";
    const schema = await fetch(
      `https://api.magica.com/api/v1/models/${modelId}/schema`,
      { headers: { Authorization: `Bearer ${process.env.MAGICA_API_KEY}` } },
    ).then((res) => res.json());

    console.log(schema.fields.filter((field) => field.required));
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    model_id = "flux-2-max-text"
    schema = requests.get(
        f"https://api.magica.com/api/v1/models/{model_id}/schema",
        headers={"Authorization": f"Bearer {os.environ['MAGICA_API_KEY']}"},
    ).json()

    print([field for field in schema["fields"] if field.get("required")])
    ```
  </Tab>
</Tabs>

Use the schema response to render client-side forms and validate required fields before sending payloads to your backend.

***

## 5. Estimate credits

Estimate cost before a model or workflow execution.

```bash theme={null}
curl -X POST https://api.magica.com/api/v1/nodes/estimate-credits \
  -H "Authorization: Bearer $MAGICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "nodes": [
      {
        "nodeType": "flux_2_max",
        "subModelId": "flux-2-max-text",
        "input": {
          "prompt": "A cinematic product photo of a glass speaker"
        }
      }
    ]
  }'
```

Check [`GET /v1/credits/balance`](/api-reference/credits/balance) before submitting expensive jobs.

***

## 6. Start a model run

```bash theme={null}
curl -X POST https://api.magica.com/api/v1/nodes/flux_2_max/run \
  -H "Authorization: Bearer $MAGICA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subModelId": "flux-2-max-text",
    "input": {
      "prompt": "A cinematic product photo of a glass speaker"
    }
  }'
```

The response includes a `runId`. Poll [`GET /v1/nodes/runs/{runId}`](/api-reference/nodes/get-model-run) until the run reaches `COMPLETED`, `FAILED`, or `CANCELED`.

For workflow execution, use [`POST /v1/runs`](/api-reference/runs/start) and poll [`GET /v1/runs/{runId}`](/api-reference/runs/get).

***

## OpenAPI spec

The full OpenAPI 3.1 specification is at:

```text theme={null}
https://api.magica.com/api/v1/openapi.json
```

Import it into Postman, Insomnia, or any OpenAPI-compatible client to generate typed SDKs.

***

## Next steps

<CardGroup cols={2}>
  <Card title="Model catalog" icon="cubes" href="/api-reference/nodes/list-models">
    Browse available models and their identifiers.
  </Card>

  <Card title="Run workflows" icon="play" href="/api-reference/runs/start">
    Start workflow runs and poll results.
  </Card>

  <Card title="Concepts" icon="book" href="/introduction/concepts">
    Understand models, nodes, credits, system workflows, and run history.
  </Card>
</CardGroup>