Run with the Sudoku API
The API is free with attribution. Design around the published limits and keep a local inventory of puzzles so gameplay does not depend on an upstream request for every move.
On this page
Capacity and quotas
Authenticated REST requests and MCP protocol requests share 6,000 requests per minute per developer account, across all its keys. Team keys use the team owner’s account quota. MCP initialization, notifications and discovery also count. PDF downloads, whether authorized by a download grant or a Bearer key, use a separate 6,000-per-minute account bucket. A batch can contain up to 20 puzzles. Separate protective limits may also apply before authentication.
The daily JavaScript/iframe widget needs no API key and does not consume these quotas. Moves, checks, hints and saved progress run inside the widget. A custom website calling the API through its backend does consume quota. Public hosting and abuse protections still apply.
When the account quota is evaluated, responses include X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Scope (api or download), and X-RateLimit-Reset (UTC Unix seconds). Rejected requests can consume quota. These are account-bucket values, not a reservation or a promise that other limits will allow your next request.
Prefetch modest batches, store generated puzzles and solutions on your server, and check moves locally. Cache completed exports and download PDFs before their 24-hour grant expires. Public collections persist separately from download grants.
Need more capacity? Contact [email protected] with expected requests per minute, daily puzzle volume and your use case. Higher limits are reviewed individually; they are not automatically available. Do not rotate keys to bypass an account limit.
Errors, retries and request IDs
REST operation POSTs, MCP POSTs and PDF downloads return X-Request-Id, including handled failures. Save it with the UTC time and HTTP status when reporting an issue. It contains no key or puzzle data.
On HTTP 429, respect Retry-After before sending another request. Retry transient read-only calls with bounded exponential backoff and jitter. Do not retry 400, 401, 403 or 409 until you fix their cause. MCP tool errors can also arrive in an HTTP 200 result: inspect isError.
Generation returns new puzzles; exports create new download grants. If either times out, the outcome is unknown. Do not blindly repeat these calls or assume exactly-once delivery. The downloadable clients avoid automatic retries for generation and exports, limit safe retries to two, and expose long retry delays for your scheduler.
Error code reference →Protect keys, answers and saved games
Use the API from your backend. Never embed a secret key or the full solution in a public browser bundle, page HTML or mobile binary. Send a puzzle and opaque game ID to your player, then validate progress on your server.
API publishing creates public URLs. Use the separate private library endpoints for private personal or team storage. Store your own game ownership, inventory and player progress. Export links expire; download and retain files you need. Keep the required hyperlink in online outputs and the printed address in offline outputs.
The starter app demonstrates this flow. Its SQLite store requires persistent disk and one application instance; use shared storage for serverless or horizontally scaled deployments.
Versions and compatibility
REST routes use /api/v1. Additive fields and optional inputs may be added within v1; clients should ignore unknown response fields. We intend to put incompatible contracts in a new major API version and announce migrations in the changelog. No fixed deprecation period is currently guaranteed.
Responses expose an engineVersion where applicable. Generator and difficulty improvements may change the puzzle returned for the same input; supply seed and generatorVersion: seed-v1 to reproduce puzzle content. No global cross-request uniqueness is promised. A seed is not confidential and does not reproduce download grants or PDF metadata. Save the actual grids for long-term archival needs. Downloaded developer kits use immutable versioned filenames and published SHA-256 checksums.
Support and availability
This is a free, best-effort service. There is no contractual uptime, response-time or support-response SLA, and no paid priority-support plan is currently offered. Use graceful failure states and a server-side puzzle inventory for availability-sensitive applications.
Contact [email protected] with a minimal example, UTC timestamp, operation, status and request ID. Remove API keys, session tokens and personal player data before sharing logs.
Current component checks →