# API reference

The portal renders the API reference as an interactive client (Scalar) over one committed
OpenAPI artifact. That live view is client-rendered, so for machine consumption use the
static sources below rather than scraping the rendered UI.

## Machine-readable sources

- **Full OpenAPI artifact** — [/openapi/thomas-federated.openapi.json](/openapi/thomas-federated.openapi.json).
  The complete, versioned specification. This is the single source of truth for every
  endpoint, request and response shape.
- **Essentials OpenAPI** — [/openapi/thomas-essentials.openapi.json](/openapi/thomas-essentials.openapi.json).
  A curated strict subset of the full artifact for the common integration path.
- **Generated operation docs** — [/docs/api/index.md](/docs/api/index.md) indexes one
  Markdown page per operation under `/docs/api/operations/`, each derived from the
  artifact (method, callable URL, parameters, request body, responses and schema refs).

## Two views, one artifact

- **Essentials** — the curated subset, the default in-portal view.
- **Full reference** — the whole artifact.

Both are the portal's own static `/openapi/` files, served at stable URLs. There is no
runtime-corrected server URL and no external redirect.

## Limits & throughput

Calls are rate-limited. When you exceed your quota, requests return `429` with a retry
hint: back off and retry. Your exact limit is shown with your key.

Working at volume? Bulk endpoints are live: import up to 100 people per call, and assign
to 100 at a time. So 10,000 people is about 100 batched calls, idempotent by email.
Result webhooks are coming soon; until then, poll the assignment status.

Bulk endpoints: `/colleagues/bulk`, `/colleagues/bulk/validate`,
`/assessments/assignments/bulk`.

## Roadmap

Result webhooks (an `assessment.completed` event) are coming soon. For now, poll the
assignment status with `getAssessmentAssignment` until `status` is `COMPLETED`.

## Where next

- [Quickstart use cases](/quickstart.md)
- [Concepts](/concepts.md)
- [Overview](/overview.md)