API Reference
Complete REST API reference for the v1 platform API. All endpoints are prefixed with /api/v1.
Use the TypeScript SDK
For most integrations, we recommend the TypeScript SDK. It handles authentication, retries, rate-limit backoff, and response typing. This REST reference is provided for custom clients or unsupported languages.
Base URL & Authentication
All endpoints require a tenant API key passed via the X-API-Key header. See Authentication for details.
Endpoint Groups
Auth
/auth/registerRegister an end-user in your tenant
/auth/loginAuthenticate with email and password
/auth/magic-linkRequest a passwordless login link
/auth/refreshExchange refresh token for new token pair
Puzzles
/puzzlesList puzzles with filtering and pagination
/puzzles/daily/:dateGet daily puzzles for a date
/puzzles/:idGet a puzzle by UUID
/puzzles/generateGenerate a new puzzle on demand
/puzzles/:id/validateValidate a puzzle solution
Analytics, Webhooks, Print, Health, GDPR
Response Format
All responses are JSON. Successful responses wrap data in a success/data envelope:
{
"success": true,
"data": { ... }
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid puzzle type",
"details": { ... }
}
}Pagination
List endpoints support page-based pagination:
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1) |
limit | integer | Items per page (default: 20, max: 100) |
Paginated responses include a pagination object:
{
"data": [...],
"pagination": {
"page": 1,
"limit": 20,
"total": 142,
"totalPages": 8
}
}Rate Limit Headers
Every response includes rate limit information:
| Header | Description |
|---|---|
X-RateLimit-Limit | Max requests per window |
X-RateLimit-Remaining | Requests remaining |
X-RateLimit-Reset | Unix timestamp when window resets |