---
summary: The full REST surface. The auto-generated Swagger is at /docs (the FastAPI
  one, not these docs).
title: API endpoints
path: reference/api-endpoints
status: published
---

# API endpoints

For an interactive view, hit `http://localhost:8000/docs` on a running
backend — that's the FastAPI-generated Swagger.

## Major route groups

| Prefix | What lives there |
|---|---|
| `/api/v1/auth/*` | Login, refresh, logout, profile |
| `/api/v1/users/*` | User CRUD |
| `/api/v1/groups/*` | Groups + members |
| `/api/v1/roles/*` | Roles + permission attachments |
| `/api/v1/permissions/*` | Permission listing |
| `/api/v1/sites/*` | Sites + domains + error pages |
| `/api/v1/content-types/*` | Schema management |
| `/api/v1/content/*` | Content CRUD, translations, revisions |
| `/api/v1/taxonomies/*` | Taxonomies + terms + content links |
| `/api/v1/assets/*` | Upload, list, file proxy |
| `/api/v1/template-packs/*` | Pack upload, set default, replace |
| `/api/v1/search/*` | Content search + index admin + queue stats |
| `/api/v1/webhooks/*` | Outbound webhook management |
| `/api/v1/form-submissions/*` | Inbox |
| `/api/v1/docs/*` | The docs subsystem |
| `/api/v1/api-keys/*` | API key issuance + revocation |
| `/api/v1/ai/*` | LLM-assisted generation |

## Response conventions

```
Success:  {field: value, ...}                     (direct model response)
List:     {"items": [...], "total": N}            (paginated)
Error:    {"detail": "message"} or
          {"detail": {"code": "X", "message": "Y"}}
```

## Authentication

Two flavors over the same `Authorization: Bearer …` header:

- **JWT** for user sessions (access token, 30 min; refresh, 7 d).
- **API key** with the `scai_` prefix; see [API keys](/docs/scaicms/concepts/api-keys).

## Site context

Content endpoints require `X-Site-ID:` matching a site you can access.
Global endpoints (users, groups, the docs subsystem) ignore it.

## Pagination

List endpoints accept `page` and `page_size` (default 50; max varies by
endpoint). The response always includes `total` so you can drive a paging UI.