---
title: API overview
path: reference/api/overview
status: published
---

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

```
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](../concepts/authentication-and-rbac).

## Error envelope

Non-2xx responses follow a consistent envelope:

```json
{
  "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](./auth) — 3 endpoints
- [Catalog](./catalog) — 4 endpoints
- [Subscriptions (tenant)](./subscriptions) — 6 endpoints
- [Service packs (tenant)](./service-packs) — 5 endpoints
- [Billing (tenant)](./billing) — 17 endpoints
- [Organization](./organization) — 4 endpoints
- [Notifications](./notifications) — 3 endpoints
- [Uploads](./uploads) — 3 endpoints
- [Metering](./metering) — 6 endpoints
- [Provisioning](./provisioning) — 4 endpoints
- [Service registry](./registry) — 4 endpoints
- [Service entrypoints](./entrypoints) — 1 endpoints
- [Inbound webhooks (payment providers)](./webhooks) — 4 endpoints
- [Service-to-platform billing](./service-billing) — 7 endpoints
- [Admin — general](./admin) — 9 endpoints
- [Admin — billing & invoices](./admin-billing) — 26 endpoints
- [Admin — tenants](./admin-tenants) — 3 endpoints
- [Admin — partners](./admin-partners) — 6 endpoints
- [Admin — subscriptions](./admin-subscriptions) — 7 endpoints
- [Admin — service packs](./admin-packs) — 5 endpoints
- [Admin — webhook subscribers](./admin-webhook-subscriptions) — 4 endpoints
- [Admin — users](./admin-users) — 6 endpoints
- [Admin — groups & roles](./admin-groups) — 4 endpoints
- [Admin — platform settings](./admin-platform) — 2 endpoints
- [Admin — accounting integrations](./admin-accounting) — 9 endpoints
- [Admin — provisioning workflows](./admin-provisioning) — 4 endpoints
- [Admin — service entrypoints](./admin-entrypoints) — 4 endpoints
- [Admin — lookup endpoints](./admin-lookups) — 3 endpoints
- [Admin — usage](./admin-usage) — 2 endpoints
- [Untagged](./untagged) — 2 endpoints

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