# Trainual API v3

> Trainual's public API for employee training, onboarding, and process documentation.
> Endpoints are served from `https://api.trainual.com`, are prefixed `/v3/`, and follow
> the [JSON:API](https://jsonapi.org/) specification. This file indexes the
> machine-readable documentation for it.

The interactive reference at <https://developers.trainual.com/> renders client-side, so
fetching it without a JavaScript runtime returns an empty page. Read the OpenAPI
specification linked below instead — it is the source of truth for every endpoint,
parameter, schema, and error response.

## Start here

**Use v3, not v1.** Trainual's V1 API is legacy and reaches end of service on
December 31, 2026. Integration code written from memory often targets v1 or omits the
`/v3/` prefix; verify every path against the specification below rather than recalling
it.

**Authentication.** Every request carries a bearer token tied to a single Trainual
user:

```
Authorization: Bearer <user_api_token>
```

Tokens are generated in the Trainual app under `My settings / Integrations & AI`. A
missing or revoked token returns `401 Unauthorized`; a valid token for an account on
trial, or whose subscription is on hold, returns `403 Forbidden`.

**Token scopes.** A token holds per-resource read and manage scopes. A `?include=` that
side-loads a resource governed by a different scope requires read access to that scope
too, and is rejected with `403 Forbidden` without it.

**Conventions.** Request and response bodies use the JSON:API document structure
(`{ "data": { "type": ..., "attributes": ... } }`), and errors are returned as a
JSON:API `errors` array. Every reference a resource holds is returned as an id
attribute (`owner_id`, `subject_id`, `question_id`); where the referenced thing is a
resource of its own, it can also be side-loaded with `?include=`, nested with dot
notation where documented (`attempt.user`). The resource named in the path is never an
include. An unsupported include returns `400 Bad Request` listing the allowed values.

**Pagination.** Collection endpoints take `page[number]` (1-based, defaults to `1`) and
`page[size]` (defaults to `10`, capped at `100`). Responses carry a `meta` object with
totals and a `links` object with ready-made URLs — follow `links.next` rather than
constructing pagination URLs.

**Rate limits.** 20 requests/second per account, shared across every token issued for
that account, plus a 25 requests/second per-IP ceiling. Both use a fixed one-second
window, so the allowance cannot be spent as a burst — pace requests evenly. Exceeding a
limit returns `429 Too Many Requests` whose body uses a `baseErrors` array, **not** the
JSON:API `errors` array used by every other error, and carries no `Retry-After` header;
retry with exponential backoff. There are no batch or bulk endpoints: prefer a larger
`page[size]` and `?include=` side-loading over many single-resource fetches, and
webhooks over polling.

**Coverage.** Users, groups, responsibilities, assignments, completions, activities,
content and content search, subjects, documents, pages, tests, flowcharts, videos,
files, checklists, courses, webhooks, webhook attempts, and MCP tokens.

## API reference

- [OpenAPI 3.0 specification](https://developers.trainual.com/openapi.yaml): the complete machine-readable spec and the only source of truth — every endpoint, parameter, schema, and error response, plus prose sections on authentication, pagination, rate limiting, webhook delivery and signature verification, and a dated changelog. Use this for code generation.

## Optional

- [Interactive reference](https://developers.trainual.com/): human-browsable documentation. Rendered client-side, so it is of no use without a JavaScript runtime.
- [Trainual help center](https://help.trainual.com/): product documentation for the Trainual app itself.
- [V1 API (legacy)](https://trainual.docs.apiary.io/): superseded by v3; end of service December 31, 2026. Reference only — do not build against it.