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:

<GATEWAY_URL>/api

For local development, the default Gateway is usually:

http://localhost:8080/api

Authentication

Server-to-server requests use an API key:

X-API-Key: <your_api_key>

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

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

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:

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