# Codeforces API > Codeforces as an API — the largest competitive-programming platform, running regular rated rounds for hundreds of thousands of programmers worldwide. This API wraps the official Codeforces API into a clean, predictable JSON service. /v1/user looks up one or many competitors' profiles — current and maximum rating with the corresponding rank/title (from newbie through grandmaster to legendary grandmaster), contribution score, country, city, organization, registration date and avatar. /v1/rating returns a competitor's full rating history, contest by contest, with the old and new rating, the rating change and the rank achieved in each round — ideal for plotting a rating curve. /v1/contests lists upcoming and past contests, filterable by phase (BEFORE for the schedule of upcoming rounds, FINISHED for the archive), each with start time, duration and type. /v1/problems searches the entire Codeforces problemset by tag (dp, graphs, greedy, math, implementation, data structures and dozens more) and by difficulty-rating range, returning each problem's contest id, index, name, difficulty rating and tags with a direct link. Ratings range from ~800 to 3500+. Ideal for competitive-programming dashboards, rating trackers, training and problem-recommendation tools, and Discord/Telegram bots for CP communities. Data from the official Codeforces API, free to use. The service is resilient to Codeforces' concurrency rate-limit (automatic retry with backoff). ## Authentication All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys. ```bash curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/codeforces-api/..." ``` ## Pricing - **Free** (Free) — 1,000 calls/Mo, 2 req/s - **Starter** ($8/Mo) — 30,000 calls/Mo, 5 req/s - **Pro** ($24/Mo) — 130,000 calls/Mo, 12 req/s - **Mega** ($64/Mo) — 520,000 calls/Mo, 35 req/s ## Endpoints ### Users #### `GET /v1/rating` — A user's rating history **Parameters:** - `handle` (query, required, string) — Codeforces handle, e.g. tourist Example: `tourist` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/codeforces-api/v1/rating?handle=tourist" ``` **Response:** ```json { "data": { "count": 303, "handle": "tourist", "current": 3428, "history": [ { "date": "2010-02-25T19:00:00.000Z", "rank": 14, "change": 1602, "contest": "Codeforces Beta Round 2", "contest_id": 2, "new_rating": 1602, "old_rating": 0 }, { "date": "2010-04-08T17:45:00.000Z", "rank": 5, "change": 162, "contest": "Codeforces Beta Round 8", "contest_id": 8, "new_rating": 1764, "old_rating": 1602 }, { "date": "2010-04-15T17:45:00.000Z", "rank": 18, "change": 114, "contest": "Codeforces Beta Round 10", "contest_id": 10, "new_rating": 1878, "old_rating": 1764 }, { "date": "2010-05-06T16:00:00.000Z", "rank": 11, "change": 89, "contest": "Codeforces Beta Round 13", "contest_id": 13, "new_rating": 1967, "old_rating": 1878 }, { "date": "2010-06-24T17:00:00.000Z", "rank": 2, "change": 96, "contest": "Codeforces Beta Round 19", " …(truncated, see openapi.json for full schema) ``` #### `GET /v1/user` — Competitor profile(s) **Parameters:** - `handle` (query, required, string) — Codeforces handle, e.g. tourist (up to 10 comma-separated) Example: `tourist` **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/codeforces-api/v1/user?handle=tourist" ``` **Response:** ```json { "data": { "count": 1, "users": [ { "city": "Gomel", "rank": "legendary grandmaster", "handle": "tourist", "rating": 3428, "country": "Belarus", "max_rank": "tourist", "max_rating": 4009, "registered": "2010-02-12T15:08:08.000Z", "title_photo": "https://userpic.codeforces.org/422/title/50a270ed4a722867.jpg", "contribution": 59, "organization": "ITMO University", "friend_of_count": 88991 } ] }, "meta": { "timestamp": "2026-06-01T16:23:51.698Z", "request_id": "8a317bb3-4aa2-4a7e-b192-e48a5c1e3d9e" }, "status": "ok", "message": "User retrieved", "success": true } ``` ### Contests #### `GET /v1/contests` — Upcoming & past contests **Parameters:** - `phase` (query, optional, string) — Filter: BEFORE, CODING, FINISHED Example: `BEFORE` - `limit` (query, optional, string) — Max results (1-100) **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/codeforces-api/v1/contests?phase=BEFORE" ``` **Response:** ```json { "data": { "count": 2, "phase": "BEFORE", "total": 2, "contests": [ { "id": 2233, "url": "https://codeforces.com/contest/2233", "name": "Educational Codeforces Round 191 (Rated for Div. 2)", "type": "ICPC", "phase": "BEFORE", "starts": "2026-06-09T14:35:00.000Z", "duration_minutes": 120 }, { "id": 2234, "url": "https://codeforces.com/contest/2234", "name": "Codeforces Round (Div. 2)", "type": "CF", "phase": "BEFORE", "starts": "2026-06-07T14:35:00.000Z", "duration_minutes": 135 } ] }, "meta": { "timestamp": "2026-06-01T16:23:51.873Z", "request_id": "ee315534-f794-4948-ab93-85b1e2eed4a2" }, "status": "ok", "message": "Contests retrieved", "success": true } ``` ### Problems #### `GET /v1/problems` — Search the problemset **Parameters:** - `tags` (query, optional, string) — Comma-separated tags, e.g. dp,graphs Example: `dp` - `min_rating` (query, optional, string) — Minimum difficulty rating - `max_rating` (query, optional, string) — Maximum difficulty rating **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/codeforces-api/v1/problems?tags=dp" ``` **Response:** ```json { "data": { "tags": [ "dp" ], "count": 30, "total": 2486, "problems": [ { "url": "https://codeforces.com/problemset/problem/2232/D", "name": "Magical Tiered Cake", "tags": [ "constructive algorithms", "dfs and similar", "dp", "greedy" ], "index": "D", "rating": null, "contest_id": 2232 }, { "url": "https://codeforces.com/problemset/problem/2232/C1", "name": "Seating Arrangement (Easy Version)", "tags": [ "binary search", "dp", "greedy", "two pointers" ], "index": "C1", "rating": null, "contest_id": 2232 }, { "url": "https://codeforces.com/problemset/problem/2231/E", "name": "Graph Cutting", "tags": [ "dfs and similar", "dp", "math", "trees" ], "index": "E", "rating": 2300, "contest_id": 2231 }, { "url": "https://codeforces.com/problemset/problem/2230/F", …(truncated, see openapi.json for full schema) ``` ### Meta #### `GET /v1/meta` — Usage notes **Example:** ```bash curl -H "x-oanor-key: $KEY" \ "https://api.oanor.com/codeforces-api/v1/meta" ``` **Response:** ```json { "data": { "note": "Codeforces is the largest competitive-programming platform, running regular rated rounds for hundreds of thousands of programmers. /v1/user?handle=tourist = a competitor's profile (current & max rating and rank/title, contribution, country, organization, registration date, avatar) — pass up to 10 comma-separated handles; /v1/rating?handle=tourist = the user's full rating history contest by contest (old/new rating, change and rank in each); /v1/contests?phase=BEFORE = upcoming and past contests (filter by phase BEFORE/CODING/FINISHED, limit 1-100) with start time, duration and type; /v1/problems?tags=dp&min_rating=1500&max_rating=2000 = search the problemset by tag(s) (e.g. dp, graphs, greedy, math, implementation) and difficulty-rating range, returning each problem's contest id, index, name, rating and tags. Ratings range from ~800 (newbie) to 3500+ (legendary grandmaster). Data from the official Codeforces API (free to use). Ideal for competitive-programming dashboards, training tools, rating trackers and problem recommenders.", "source": "Codeforces API (codeforces.com/api)", "endpoints": [ "/v1/user", "/v1/rating", "/v1/contests", "/v1/problems", "/v1/meta" ] }, "meta": { "timestamp": "2026-06-01T16:23:52.322Z", "request_id": "a83b025c-cdae-4ae2-ab40-0c478190b141" }, "status": "ok", "message": "Meta retrieved", "succ …(truncated, see openapi.json for full schema) ``` --- Marketplace page: https://www.oanor.com/api/codeforces-api OpenAPI spec: https://www.oanor.com/api/codeforces-api/openapi.json