API Reference
The Imperal Cloud public REST API — auth, extensions, marketplace, billing, developer portal, and real-time events. Build on the platform without touching the web-kernel.
The Imperal Cloud REST API is the integration surface for every client that talks to the platform without embedding Python extension code. It is the same surface the Imperal Panel, the Developer Portal, and the web-kernel itself use for user-facing operations.
What is exposed here
Two services are documented:
- Auth Gateway (
auth.imperal.io) — identity, JWT auth, extensions, marketplace, billing, developer portal, secrets, tenants, events. The primary surface for developers integrating with Imperal Cloud. - Registry (
api-server) — extension discovery, tool manifests, app settings. Used by the web-kernel at session start and by clients that need the full tool catalog.
This reference covers the public developer surface only. Internal kernel-to-gateway routes (those under /v1/internal/* or tagged *-internal) are not listed. A small number of routes visible in the downloadable spec require an X-Service-Token issued to trusted backend callers — these are labeled kernel/service-only in the API map.
Authentication
All authenticated endpoints accept one of two credentials in the request header:
| Credential | Header | Issued by | For |
|---|---|---|---|
| Bearer JWT | Authorization: Bearer <token> | POST /v1/auth/login | User-facing clients, extensions, third-party integrations |
| Service token | X-Service-Token: <token> | Platform ops | Trusted backend callers (kernel-only; not for developer use) |
Obtain a Bearer JWT with the login flow:
curl -s -X POST https://auth.imperal.io/v1/auth/login \
-H 'Content-Type: application/json' \
-d '{"email":"you@example.com","password":"...","tenant_id":"default"}' \
| jq '.access_token'Pass the resulting token on every subsequent request:
curl -s https://auth.imperal.io/v1/auth/me \
-H 'Authorization: Bearer <access_token>'Where to go next
| Topic | Page |
|---|---|
| Curated key-endpoint quickstart with curl examples | API map |
| Full Auth Gateway surface — all public endpoint groups | Auth Gateway |
| Registry — extension discovery and tool manifests | Registry |
Downloadable specs
The machine-readable OpenAPI 3.1 specs are available as static JSON downloads:
- Auth Gateway public spec:
/openapi/auth-gateway.json - Registry spec:
/openapi/registry.json
Or fetch the Auth Gateway spec live (always current):
curl -s https://auth.imperal.io/v1/openapi.json | python3 -m json.tool | head -20Payouts
Payouts to USD via Stripe Connect for Imperal Cloud developers — verify your account once, request a payout anytime, and get paid in two to seven business days.
Developer API Map
Curated quickstart for the Imperal Cloud public API — services overview, the 15 key endpoints with curl examples, and gotchas every developer should know.