---
summary: The REST surface, authentication, and error format.
title: API reference
path: api-reference
status: published
---

# API reference

ScaiCrew exposes a REST API under `/v1`. Interactive docs are available at `/docs` (OpenAPI at
`/openapi.json`).

## Authentication

Send one of:

- **`Authorization: Bearer <session-token>`** — the token minted by [login](/docs/scaicrew/authentication/login)
  (the normal path for the Bridge).
- **`Authorization: Bearer <service-token>`** — a ScaiKey service token (validated via JWKS).
- **`X-Dev-*` headers** — dev mode only (`ENV=dev`).

The workspace and role are taken from the token, never from the request body.

## Errors

Errors use RFC-7807 problem+json:

```json
{ "error": { "code": "NotFound", "message": "…", "details": {}, "trace_id": "…" } }
```

## Endpoints (implemented)

| Area | Endpoints |
|---|---|
| Auth | `POST /v1/auth/login`, `GET /v1/auth/callback`, `POST /v1/auth/token`, `POST /v1/auth/refresh` |
| Me / workspaces | `GET /v1/me/workspaces`, `GET /v1/workspace`, `PATCH /v1/workspace` |
| Crews | `GET/POST /v1/crews`, `GET /v1/crews/{id}/members` |
| Members | `GET/POST /v1/members`, `POST /v1/members/{id}/publish`, `GET /v1/members/{id}/versions/{n}` |
| Handoffs | `PUT /v1/members/{id}/handoffs` |
| Runs | `GET /v1/runs`, `GET /v1/runs/{id}`, `GET /v1/runs/{id}/events`, `POST /v1/members/{id}/runs` |
| Approvals | `GET /v1/approvals`, `POST /v1/approvals/{id}/approve`, `POST /v1/approvals/{id}/reject` |
| Triggers | `POST/GET /v1/triggers`, enable/disable, public webhook ingress |
| Authoring | `POST /v1/authoring/sessions`, `…/turn`, `GET …/sessions/{id}` |
| Templates | `GET /v1/templates`, `GET /v1/templates/{ref}`, `POST /v1/templates/{ref}/install` |
| Bridge | `GET /v1/cost`, `GET /v1/schedules`, `GET /v1/stream` (SSE) |

## Deferred (return `501`)

Run retry, mail triggers, the "Open in ScaiFlow" export, and template upgrade are intentionally not
implemented yet and return `501 Not Implemented` rather than a stub response.