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

# REST API

> Public request shape, authentication headers, and model execution examples.

# REST API

Use the REST API when your own backend, worker, or script needs to execute a
published model. Public consumers should call the Gateway. Do not call internal
services directly.

## Base URL

Use the Gateway URL for your environment:

```text theme={null}
<GATEWAY_URL>/api
```

For local development, the default Gateway is usually:

```text theme={null}
http://localhost:8080/api
```

## Authentication

Server-to-server requests use an API key:

```http theme={null}
X-API-Key: <your_api_key>
```

Browser requests made by the signed-in product app use a user access token:

```http theme={null}
Authorization: Bearer <access_token>
```

Do not put long-lived API keys in browser JavaScript.

Do not send an API key as a bearer token. `Authorization: Bearer <access_token>`
is only for signed-in browser sessions; developer integrations should use
`X-API-Key`.

## Execute a model

```bash theme={null}
curl -X POST "$AIMP_GATEWAY_URL/api/runs" \
  -H "X-API-Key: $AIMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "demo-model",
    "mode": "execute",
    "scope": "playground",
    "input": {
      "text": "Hello"
    },
    "params": {}
  }'
```

## Request fields

| Field     | Required  | Meaning                                                                                                        |
| --------- | --------- | -------------------------------------------------------------------------------------------------------------- |
| `model`   | Yes       | The published model slug or identifier.                                                                        |
| `mode`    | No        | The operation to run. Defaults to `execute`.                                                                   |
| `scope`   | Sometimes | Required for vector-enabled modes. It is the vector namespace that separates indexed datasets.                 |
| `input`   | Yes       | Model input. Shape depends on the model contract.                                                              |
| `params`  | No        | Model parameters. Must be a JSON object.                                                                       |
| `options` | No        | Allowed execution options. Do not send `hardware_tier`; hardware is resolved from the published model release. |

Use `params`, not `parameters`. Vector routing fields such as `resources`,
`alias`, `collection`, and `namespace` are managed by the platform and must not
be supplied by clients.

For vector-backed `index` and `search` modes, use the same `scope` for the data
you want to search. For example, if images are indexed with `scope: "test"`,
search requests must also use `scope: "test"`. Knowledge Bases displays indexed
data by model, collection, and scope.

Valid scopes start with a letter or number, may contain letters, numbers, `.`,
`_`, and `-`, and are limited to 64 characters.

## Upload media for model inputs

Models that accept images, audio, video, or files use `media_ref` values in
`input`. Upload the file through the public media API first:

```bash theme={null}
curl -X POST "$AIMP_GATEWAY_URL/api/media/upload/init" \
  -H "X-API-Key: $AIMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filename": "image.png",
    "content_type": "image/png",
    "media_type": "image",
    "size_bytes": 12345
  }'
```

Upload the file bytes to the returned `upload_url`, then complete the upload:

```bash theme={null}
curl -X POST "$AIMP_GATEWAY_URL/api/media/upload/complete" \
  -H "X-API-Key: $AIMP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "upload_id": "studio_upload_..."
  }'
```

Use the returned `media_ref` inside `POST /api/runs`.

## Related APIs

* `GET /api/marketplace/models` lists published Marketplace models.
* `GET /api/marketplace/models/{slug}` loads one Marketplace model detail page.
* `POST /api/media/upload/init` starts a developer media upload.
* `POST /api/media/upload/complete` returns the `media_ref` for a completed upload.
* `GET /api/billing/wallet` loads the current workspace wallet.
* `GET /api/billing/usage/summary` loads usage summary for the current workspace.