Execute via API

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

Execute via API

The public run endpoint is:

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

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

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

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:

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:

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:

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:

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.