REST API · V1
One Move API
Base URL https://api.getonemove.app. Versioned base https://api.getonemove.app/v1. OpenAPI 3.1 at https://api.getonemove.app/openapi.json.
Authentication
Public reads are anonymous: GET /v1/constraints, GET /v1/free-reports/{site}/{username} and GET /v1/jobs/{id} need no credentials. For attributable limits, register an OAuth client and use client_credentials.
curl -sS -X POST https://api.getonemove.app/v1/clients \
-H 'Content-Type: application/json' \
-d '{"client_name":"my-agent"}'
curl -sS -X POST https://api.getonemove.app/oauth2/token \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&client_id=...&client_secret=...'Send Authorization: Bearer <access_token>. Discovery documents: protected resource and authorization server. The full agent walkthrough is auth.md.
Scopes
| Scope | Grants |
|---|---|
reports:read | Read public reports, jobs, constraints and documentation. |
reports:write | Queue a report or submit a batch. |
docs:read | Read documentation through the docs MCP server. |
Endpoints
GET /v1/constraints
The Constraint catalog with Targets by Band. Cursor pagination: limit (1–50, default 20), cursor and optional subject=chess|poker. Response: { data, next_cursor, has_more }.
GET /v1/constraints/{slug}
One Constraint, its metric definition, direction and chess medians by Band.
GET /v1/free-reports/{site}/{username}
site is chesscom or lichess. Optional time_class=rapid|blitz. Anonymous.
| Status | Meaning |
|---|---|
| 200 | Report is ready. |
| 202 | Queued or running. Body has job_id, status, status_url and minutes. |
| 404 | Not enough games, or unknown user. |
| 429 | Over the budget; Retry-After is set. |
GET /v1/jobs/{job_id}
Async-job pattern: queued, running, done or failed, plus status_url and, when done, result_url.
POST /v1/reports
Queue a report from JSON: { site, username, time_class }. Returns 202 with a job. Supports Idempotency-Key.
POST /v1/batch
Up to 10 read operations in one request. Each operation has id, tool and arguments. Tools: constraints.get, constraints.list, report.get. Supports Idempotency-Key.
GET /v1/sandbox/reports/{site}/{username}
A fixed synthetic report for schema tests. It never reads a real account, queues work, or calls Claude. Use it before touching a real username.
POST /v1/clients
Self-serve OAuth client registration. Returns a client id, a secret shown once, and the three scopes. Rate limited.
POST /ask
NLWeb v0.55 natural-language search over the docs and Constraint catalog. Body { query: { text }, prefer: { streaming } }. With prefer.streaming=true or Accept: text/event-stream, returns the NLWeb SSE events start, result, complete.
Idempotency
All POST, PUT and PATCH requests accept an Idempotency-Key header. A replay with the same key and body returns the first response, status included, for 24 hours. A different body returns 409.
Pagination
List endpoints are cursor-based and return data, next_cursor and has_more. Treat the cursor as opaque.
Errors
Errors are JSON: { detail } or { error: { code, message } }. Status codes: 400 invalid input, 401 auth required, 404 not found, 409 idempotency conflict, 422 validation, 429 rate limited, 500 server error.
Deprecation
Deprecated endpoints return Deprecation and Sunset headers and remain available for at least 90 days. The changelog is at https://api.getonemove.app/v1/deprecation.