# API reference

Every operation, parameter, response and field, generated from the OpenAPI contract the API serves.

The reference pages are generated from the same contract the API serves at [`https://api.kapiworks.com/v1/openapi.json`](https://api.kapiworks.com/v1/openapi.json), during each release of these docs. Download it to generate a client or to diff one revision against another. This is contract revision 1.2.0.

## Base URL

`https://api.kapiworks.com/v1`

Every endpoint answers `GET` and `HEAD` over HTTPS, with JSON. Send the company API key in the `Authorization` header; see [Authentication](https://docs.kapiworks.com/authentication).

## Operations

| Endpoint | Returns | Scope |
| --- | --- | --- |
| [`GET /v1/training-records`](https://docs.kapiworks.com/reference/list-training-records) | Training records at a moment | `training:read` |
| [`GET /v1/training-records/period`](https://docs.kapiworks.com/reference/list-period-training-records) | Every training record owed during a period | `training:read` |
| [`GET /v1/certificates`](https://docs.kapiworks.com/reference/list-certificates) | Certificates at a moment | `certificates:read` |
| [`GET /v1/people`](https://docs.kapiworks.com/reference/list-people) | Employees and invitations during a period | `people:read` |
| [`GET /v1/courses`](https://docs.kapiworks.com/reference/list-courses) | Course versions referenced by employee records | `training:read` |
| [`GET /v1/snapshot`](https://docs.kapiworks.com/reference/get-snapshot) | Check whether anything changed | Any |

## Every response

* `X-Request-Id`: a UUID for this call. Quote it to [support](https://docs.kapiworks.com/support).
* `Cache-Control: no-store`: responses hold company data, so nothing on the way may store them.
* `RateLimit-Policy` and `RateLimit`: your remaining calls this minute, for the key and for the company. See [Rate limits](https://docs.kapiworks.com/rate-limits).

Errors are `application/problem+json` with a stable `code`; see [Errors](https://docs.kapiworks.com/errors).

## Paged registers

Registers answer one page at a time, with the same envelope: `data`, `total`, `snapshot` and `next_cursor`. Follow `next_cursor` until it is null; [Keeping data in sync](https://docs.kapiworks.com/guides/sync) explains how.

The [field dictionary](https://docs.kapiworks.com/reference/field-dictionary) explains every field of every register.