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.

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; commonly playground for interactive tests.
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.

Related APIs

• GET /api/marketplace/models lists published Marketplace models.
• GET /api/marketplace/models/{slug} loads one Marketplace model detail page.
• GET /api/billing/wallet loads the current workspace wallet.
• GET /api/billing/usage/summary loads usage summary for the current workspace.