InstantMLDocs

API authentication

Understand hosted base URLs, SDK API keys, and bearer authentication.

Open .md

Authenticate every InstantML API call with one of two credentials:

CredentialTransportMain use
Browser sessioninstantml_session HttpOnly cookieDashboard after hosted sign-in
SDK API keyAuthorization: Bearer instantml_...SDK, uploader, import, export, usage, and automation calls

Bootstrap/operator tokens are intentionally outside the public hosted API contract.

Call the API with a key

Send an API key as a bearer token on any direct HTTP call:

bash
curl https://api.instantml.ai/projects \
  -H "Authorization: Bearer instantml_..."

Create and manage keys in dashboard settings. Each key carries explicit scopes such as sdk:ingest (writes), export:read (reads), artifacts:write, imports:write, runs:control, and usage:read. Endpoint pages state the scope each route needs.

Use the base URL

All examples in this section target the hosted public router:

text
https://api.instantml.ai

The current public client contract is one stable API base URL. The frontend usually calls the API through same-origin Next rewrites, while SDK/API-key clients call the API base directly.

Configure the SDK

Set an API key in the environment:

bash
export INSTANTML_API_KEY="instantml_..."

Or pass it directly:

python
import instantml as im

run = im.init(
    project="demo",
    api_key="instantml_...",
    base_url="https://api.instantml.ai",
)

Handle common errors

All JSON API errors use HTTP status codes and a body with at least an error string. Some errors also include a stable code.

Hosted tenant warehouse wake/start failures return 503 with code: "warehouse_unavailable". Treat this as a retryable "warehouse is starting" state, not as an authentication failure.

Next steps