# Kapi Works API

> Read a company's employee training records, deadlines, completions and certificates from your own server. A read-only REST API over HTTPS with JSON responses, company API keys and an OpenAPI 3.1 contract (revision 1.2.0).

- Base URL: https://api.kapiworks.com/v1
- OpenAPI contract: https://api.kapiworks.com/v1/openapi.json
- Every page below is also Markdown: add .md to its address, or send Accept: text/markdown.
- Docs MCP server (streamable HTTP, read-only): https://docs.kapiworks.com/api/mcp
- All pages in one file: https://docs.kapiworks.com/llms-full.txt

## Get started

- [Overview](https://docs.kapiworks.com/): Read a company's employee training records, deadlines, completions and certificates from your own server.
- [Quickstart](https://docs.kapiworks.com/quickstart): Create a key, keep it on your server, and read your first page of training records.
- [Authentication](https://docs.kapiworks.com/authentication): Company API keys, sent from your server over HTTPS in the Authorization header.
- [Scopes](https://docs.kapiworks.com/scopes): What each scope lets a key read, and which fields need people:read.
- [API keys](https://docs.kapiworks.com/keys): Expiry, networks, rotation, notices and the record of calls a company keeps for each key.

## Guides

- [Keeping data in sync](https://docs.kapiworks.com/guides/sync): Pull every page of a snapshot, check it belongs to the right company, and replace your copy only after a complete pull.
- [The five registers](https://docs.kapiworks.com/guides/registers): What each register returns, at a moment or over a period, and how dates and the company's time zone work.
- [Training evidence](https://docs.kapiworks.com/guides/training-evidence): Outcomes, completions, certificates and check codes, and how to find training that is missing.
- [When a company's contract ends](https://docs.kapiworks.com/guides/company-ends): The Sunset header, what keeps working until the deletion date, and what to copy before it.
- [Sandbox company](https://docs.kapiworks.com/guides/sandbox): A pretend company on the live system, full of fictional people, for building and testing an integration.
- [Example app](https://docs.kapiworks.com/guides/example-client): A runnable Node 24 receiving server that pulls all five registers safely, with its full source.

## Reference

- [API reference](https://docs.kapiworks.com/reference): Every operation, parameter, response and field, generated from the OpenAPI contract the API serves.
- [Training records at a moment](https://docs.kapiworks.com/reference/list-training-records): Every record an employee owes at as_at, with its outcome then. Requires training:read. Names, work emails and certificate check codes also need people:read; without it they are left out.
- [Every training record owed during a period](https://docs.kapiworks.com/reference/list-period-training-records): Every record owed at any time between from and to, with its outcome at the end of the period or when it ended. Requires training:read. Names, work emails and certificate check codes also need people:read; without it they are left out.
- [Certificates at a moment](https://docs.kapiworks.com/reference/list-certificates): Employee certificates issued by as_at, with their state then. Requires certificates:read. Names, work emails and certificate check codes also need people:read; without it they are left out.
- [Employees and invitations during a period](https://docs.kapiworks.com/reference/list-people): Employees and invitation records that existed between from and to. Requires people:read. Names, work emails and certificate check codes also need people:read; without it they are left out.
- [Course versions referenced by employee records](https://docs.kapiworks.com/reference/list-courses): The published course versions behind employee training records, with their content fingerprints. Requires training:read. Names, work emails and certificate check codes also need people:read; without it they are left out.
- [Check whether anything changed](https://docs.kapiworks.com/reference/get-snapshot): Returns the company's latest snapshot in one call, with any scope. If sequence and capture_sequence match your last complete pull, no recorded facts have changed since. Outcomes that depend on the clock, such as not_due_yet becoming overdue, can still change, so recompute them from due_at or pull again at least daily.
- [Field dictionary](https://docs.kapiworks.com/reference/field-dictionary): What every field of every register means, from the same dictionary as the records packs.

## Help

- [Errors](https://docs.kapiworks.com/errors): Every error code the API returns, with what it means and what your integration should do.
- [invalid_request](https://docs.kapiworks.com/errors/invalid_request): Invalid request
- [invalid_cursor](https://docs.kapiworks.com/errors/invalid_cursor): Invalid cursor
- [key_in_url](https://docs.kapiworks.com/errors/key_in_url): API key revoked
- [invalid_token](https://docs.kapiworks.com/errors/invalid_token): Invalid API key
- [insufficient_scope](https://docs.kapiworks.com/errors/insufficient_scope): Scope required
- [ip_not_allowed](https://docs.kapiworks.com/errors/ip_not_allowed): Network not allowed
- [not_found](https://docs.kapiworks.com/errors/not_found): Not found
- [method_not_allowed](https://docs.kapiworks.com/errors/method_not_allowed): Method not allowed
- [before_history](https://docs.kapiworks.com/errors/before_history): History unavailable
- [record_too_large](https://docs.kapiworks.com/errors/record_too_large): Record too large
- [rate_limited](https://docs.kapiworks.com/errors/rate_limited): Too many requests
- [concurrent_limit](https://docs.kapiworks.com/errors/concurrent_limit): Too many requests at once
- [read_failed](https://docs.kapiworks.com/errors/read_failed): Records unavailable
- [unavailable](https://docs.kapiworks.com/errors/unavailable): API unavailable
- [upstream_unavailable](https://docs.kapiworks.com/errors/upstream_unavailable): Temporarily unavailable
- [writer_unavailable](https://docs.kapiworks.com/errors/writer_unavailable): History catching up
- [read_timeout](https://docs.kapiworks.com/errors/read_timeout): Read timed out
- [Rate limits](https://docs.kapiworks.com/rate-limits): How many calls a key and a company can make, what counts, and how to slow down when told to.
- [Versioning](https://docs.kapiworks.com/versioning): What can change within v1, and how breaking changes are announced.
- [Changelog](https://docs.kapiworks.com/changelog): Changes to the Kapi Works API and these docs, newest first.
- [Security](https://docs.kapiworks.com/security): How the API protects keys and company data, and how to report a security problem.
- [Support](https://docs.kapiworks.com/support): How to get help with the Kapi Works API, and what to send.
- [AI tools](https://docs.kapiworks.com/ai-tools): Read these docs as Markdown, give them to a model with llms.txt, or connect an agent to the docs MCP server.

## Optional

- [OpenAPI contract](https://api.kapiworks.com/v1/openapi.json): the machine-readable description of every operation, schema and error code