API overview

ScaiControl exposes a single REST API at /api/v1. All endpoints take and return JSON unless explicitly noted.

Base URL#

• Production: https://www.scailabs.ai/api/v1
• Local/dev: http://localhost:8000/api/v1

Authentication#

All endpoints other than /auth/config require a Bearer token issued by ScaiKey. The token's claims (sub, tenant_id, partner_id, roles, permissions) flow into FastAPI dependencies for tenant filtering and RBAC.

1

Authorization: Bearer <jwt>

Most admin endpoints additionally check a permission scope via require_permission("<scope>"). Roles map to permission sets server-side; see Authentication & RBAC.

Error envelope#

Non-2xx responses follow a consistent envelope:

1
2
3
4
5
6
7

{
  "error": {
    "code": "not_found",
    "message": "Invoice 'foo' not found",
    "request_id": "req_…"
  }
}

Common codes: not_found (404), bad_request (400), conflict (409), forbidden (403), unauthorized (401), internal_error (500).

Versioning#

The API uses a single major version (v1) baked into the URL. Backwards-compatible field additions to responses do not bump the version; breaking changes ship under v2 once they accumulate.

Endpoint groups#

• Authentication — 3 endpoints
• Catalog — 4 endpoints
• Subscriptions (tenant) — 6 endpoints
• Service packs (tenant) — 5 endpoints
• Billing (tenant) — 17 endpoints
• Organization — 4 endpoints
• Notifications — 3 endpoints
• Uploads — 3 endpoints
• Metering — 6 endpoints
• Provisioning — 4 endpoints
• Service registry — 4 endpoints
• Service entrypoints — 1 endpoints
• Inbound webhooks (payment providers) — 4 endpoints
• Service-to-platform billing — 7 endpoints
• Admin — general — 9 endpoints
• Admin — billing & invoices — 26 endpoints
• Admin — tenants — 3 endpoints
• Admin — partners — 6 endpoints
• Admin — subscriptions — 7 endpoints
• Admin — service packs — 5 endpoints
• Admin — webhook subscribers — 4 endpoints
• Admin — users — 6 endpoints
• Admin — groups & roles — 4 endpoints
• Admin — platform settings — 2 endpoints
• Admin — accounting integrations — 9 endpoints
• Admin — provisioning workflows — 4 endpoints
• Admin — service entrypoints — 4 endpoints
• Admin — lookup endpoints — 3 endpoints
• Admin — usage — 2 endpoints
• Untagged — 2 endpoints

Each group page lists every endpoint with its parameters, request body shape, response shape, and the permission scope required.