Developer documentation
API reference
Choose the correct v1 operation, request fields, response type, and machine-readable contract.
- Audience
- All API integrators
- Before you start
- A server-side API key; call the catalog before constructing generation entries
v1 operations
| Operation | Success | Output | Usage |
|---|---|---|---|
GET /api/public/v1/catalog | 200 | Direct JSON array of grades and topics | Free |
POST /api/public/v1/worksheets | 200 | application/json | 1 credit per exercise |
POST /api/public/v1/worksheets/pdf | 200 | application/pdf | 1 credit per exercise |
POST /api/public/v1/worksheets/latex | 200 | JSON with data.latex | 1 credit per exercise |
POST /api/public/v1/embeds | 201 | JSON with embedId and embedUrl | 1 credit per exercise; free views |
Common generation fields
| Field | Requirement | Behavior |
|---|---|---|
entries | Required | Non-empty array; at most 150 total problems |
entries[].id | String | Caller-selected and echoed in order. Use unique values; duplicate ids are outside the supported contract. |
grade / topic | Catalog ids | The topic must have implemented: true |
difficulty | easy | medium | hard | Must be listed in difficulties for the topic |
count | Integer 1–30 | Exact problem count for that entry |
locale | en | es | Optional; defaults to en. An unrecognized value currently also falls back to en, but do not depend on that tolerance. |
seed | Optional integer | The same seed + entries + locale reproduces prompts and answers; problem UUIDs may change. |
Response shapes
- The catalog returns its array directly; it is not wrapped in data.
- JSON, LaTeX, and embeds return { data: ... }.
- PDF returns application/pdf bytes with Content-Disposition: attachment.
- Handled errors return { error: { code, message } }. An unhandled infrastructure failure may return a generic 5xx response; do not parse message as a stable identifier.
Contracts and tools
The OpenAPI file is the machine-readable source for routes, schemas, statuses, and headers. The Postman collection exercises the same operations. Download them rather than copying a version of this page.
mock-partner is a dependency-free console that keeps the key in a Node server and lets you exercise all five operations and their headers.