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

# Execute via API

> Run a published model with curl, Python, or JavaScript.

# Execute via API

The public run endpoint is:

```text theme={null}
POST /api/runs
```

Every run must include a model, an input object, and optional operation
parameters.

Developer integrations authenticate with `X-API-Key`. Do not pass API keys in
`Authorization: Bearer`; bearer tokens are for signed-in product sessions.

## curl

```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": "Write a one-line summary."
    },
    "params": {}
  }'
```

## Python

```python theme={null}
import os
import requests

gateway_url = os.environ["AIMP_GATEWAY_URL"].rstrip("/")
api_key = os.environ["AIMP_API_KEY"]

response = requests.post(
    f"{gateway_url}/api/runs",
    headers={
        "X-API-Key": api_key,
        "Content-Type": "application/json",
    },
    json={
        "model": "demo-model",
        "mode": "execute",
        "scope": "playground",
        "input": {"text": "Write a one-line summary."},
        "params": {},
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())
```

## JavaScript

```javascript theme={null}
const gatewayUrl = process.env.AIMP_GATEWAY_URL.replace(/\/$/, "");

const response = await fetch(`${gatewayUrl}/api/runs`, {
  method: "POST",
  headers: {
    "X-API-Key": process.env.AIMP_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "demo-model",
    mode: "execute",
    scope: "playground",
    input: { text: "Write a one-line summary." },
    params: {},
  }),
});

if (!response.ok) {
  throw new Error(`AIMP request failed: ${response.status}`);
}

console.log(await response.json());
```

## Validation checklist

* `model` is a published model slug or identifier.
* `mode` exists on the model contract.
* `input` matches the model input schema.
* `params` is an object, even when empty.
* `scope` is present for vector-enabled modes.
* `index` and `search` use the same `scope` when they should read/write the
  same vector dataset.

## Index and search a vector model

File inputs must be uploaded before execution. Start the upload:

```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` to index into a vector namespace:

```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": "clipo",
    "mode": "index",
    "scope": "test",
    "input": {
      "images": [
        {
          "media_ref": "media_...",
          "filename": "image.png"
        }
      ],
      "image_ids": ["image-1"]
    },
    "params": {}
  }'
```

Search the same indexed data by using the same `scope`:

```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": "clipo",
    "mode": "search",
    "scope": "test",
    "input": {
      "image": {
        "media_ref": "media_...",
        "filename": "query.png"
      }
    },
    "params": {}
  }'
```

Indexed data appears in Knowledge Bases as model, collection, and scope.