Vesus APIvesus.org ↗
Access chess tournament and event data from vesus.org: upcoming events, venues, prize money, time controls, round counts, federation info, and organiser details.
What is the Vesus API?
The Vesus.org API exposes 3 endpoints for retrieving chess tournament and event data from vesus.org. Use list_events to browse and filter upcoming or past tournaments by country, location, attendance mode, or rated status — each result includes nested tournament arrays with registration counts and time control types. get_event and get_tournament return venue addresses, prize details, organiser contacts, federation codes, and per-period time control configurations.
curl -X GET 'https://api.parse.bot/scraper/b399456b-6da2-4fff-aa0f-5120a16986b8/list_events?limit=5&rated=false&timing=FUTURE&country_code=ITA&attendance_mode=INPERSON&tournament_type=INDIVIDUAL&time_control_type=BLITZ' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace vesus-org-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Vesus Chess Tournaments API — browse events, drill into details."""
from parse_apis.vesus_org_api import Vesus, Timing, TimeControlType, ResourceNotFound
client = Vesus()
# List upcoming blitz chess events in Italy (auto-paginated, capped at 5 total)
for event in client.events.search(timing=Timing.FUTURE, country_code="ITA", limit=5):
print(event.name, "|", event.location, "|", event.confirmed_registrations, "registered")
# Take one event and drill into its tournament details
event = client.events.search(timing=Timing.FUTURE, limit=1).first()
if event:
tournament_summary = event.tournaments[0]
detail = tournament_summary.details()
print(detail.event_name, "—", detail.rounds, "rounds,", detail.time_control[0].white_minutes, "min")
# Get full event details (venue, prize money, organiser)
if event:
tournament = client.tournaments.get(short_key=event.tournaments[0].short_key)
try:
event_detail = client.event_details.get(short_key=tournament.event_short_key)
print(event_detail.name, "|", event_detail.venue, "|", event_detail.organiser)
except ResourceNotFound as exc:
print(f"Event not found: {exc}")
print("exercised: events.search / tournament_summary.details / tournaments.get / event_details.get")
Search and list chess events/tournaments with optional filters. Returns paginated results ordered by start date. Each event includes its tournaments with registration counts, time control types, and status. Results are auto-iterated across pages.
| Param | Type | Description |
|---|---|---|
| name | string | Filter events by name (partial match). |
| after | string | Cursor for pagination. Use end_cursor from previous response to get next page. |
| limit | integer | Number of events per page (max results to return). |
| rated | string | Filter by rated status. Pass 'true' for rated tournaments only, 'false' for unrated only. Omit for all. |
| timing | string | Event timing filter. |
| location | string | Filter events by location/city name. |
| country_code | string | ISO 3-letter country code to filter events by country (e.g. ITA, DEU, GBR). Omit for all countries. |
| attendance_mode | string | Attendance mode filter. Accepted values: INPERSON, ONLINE. Omit for all. |
| tournament_type | string | Tournament type filter. Accepted values: INDIVIDUAL, TEAM. Omit for all. |
| time_control_type | string | Comma-separated list of time control types to filter by. Accepted values: BLITZ, RAPID, CLASSICAL, STANDARD. Omit for all. |
{
"type": "object",
"fields": {
"events": "array of event objects with tournaments",
"end_cursor": "string, pagination cursor for next page",
"has_next_page": "boolean"
},
"sample": {
"data": {
"events": [
{
"id": "ZXZlbnQ6Mzc5NTA1ZmQtMjI1OC00NmQ4LWExYjAtZDY5N2YyOWExMTg2",
"end": "2026-07-02T21:00:00.000Z",
"name": "3 a tappa - Circuito serale THUNDER THURSDAY",
"start": "2026-07-02T19:00:00.000Z",
"location": "Canegrate",
"tournaments": [
{
"end": "2026-07-02T21:00:00.000Z",
"name": null,
"type": "INDIVIDUAL",
"rated": false,
"start": "2026-07-02T19:00:00.000Z",
"rounds": 5,
"short_key": "cnw-opsw",
"attendance_mode": "INPERSON",
"time_control_type": "BLITZ",
"registration_status": "OPEN",
"confirmed_registrations": 8
}
],
"country_code": "ITA",
"registrations_limit": 30,
"confirmed_registrations": 8
}
],
"end_cursor": "RXZlbnRFZGdlOnsib2Zmc2V0IjoyMH0=",
"has_next_page": true
},
"status": "success"
}
}About the Vesus API
Event Listing and Filtering
The list_events endpoint returns paginated chess events ordered by start date. Each event object carries an array of its constituent tournaments, including registration counts, time control category, and status flags. Filters include country_code (ISO 3-letter, e.g. ITA, GBR), location for city-level narrowing, attendance_mode accepting INPERSON or ONLINE, rated for rated/unrated filtering, and a name partial-match filter. Pagination is cursor-based: the response returns end_cursor and has_next_page, and you pass end_cursor back as the after parameter to advance through results.
Event Detail
The get_event endpoint accepts a short_key string (obtainable from list_events tournament objects) and returns the full record for one event: ISO datetimes for start and end, venue, location, province, region, organiser name, and a country object containing code, name, timezone, and currency. Contact details and regulation information are also included where available on the source.
Tournament Configuration
The get_tournament endpoint fetches the technical setup of a single tournament. The time_control field is an array of period objects, each specifying white_minutes and black_minutes, covering multi-period classical and increment formats. Additional fields include rounds (integer), federation (object with code and acronym), and event_short_key linking back to the parent event — which you can then pass to get_event to retrieve venue and organiser context. The name field is null when the tournament name matches its parent event.
The Vesus API is a managed, monitored endpoint for vesus.org — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when vesus.org changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official vesus.org API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a chess tournament calendar filtered by country code and attendance mode for a specific national federation.
- Aggregate prize money and organiser data across upcoming events to compare competitive opportunities by region.
- Identify rated vs. unrated tournaments in a city using the
ratedandlocationfilters onlist_events. - Extract time control configurations per tournament to categorise events as classical, rapid, or blitz.
- Track tournament registration counts over time by periodically polling
list_eventsfor a given location. - Link tournament federation codes to external rating system lookups by pairing
get_tournamentfederation data with player databases. - Populate an event-discovery app with venue addresses and organiser contacts pulled from
get_event.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does vesus.org offer an official developer API?+
How does pagination work in `list_events`, and what triggers a new page?+
end_cursor (a string) and has_next_page (boolean). When has_next_page is true, pass the end_cursor value as the after parameter in your next request to retrieve the following page of results. You can also control page size with the limit parameter.Does `get_tournament` return player registrations or individual participant data?+
rounds, time_control periods, federation, schedule, arbiters, and the parent event_short_key. Registration counts appear at the summary level in list_events tournament objects, but individual participant names, ratings, or pairings are not currently exposed. You can fork this API on Parse and revise it to add an endpoint covering participant-level data.Can I filter `list_events` by time control type (classical, rapid, blitz)?+
time_control_type filter parameter on list_events. The endpoint returns time control data per tournament in the response, so you can filter client-side by inspecting the nested tournament objects. You can fork this API on Parse and revise it to add a server-side time control filter parameter.Is historical event data available, or only upcoming tournaments?+
timing parameter on list_events controls event timing, so past events can be queried where the source retains them. However, coverage depth for historical records depends on what vesus.org indexes — older events with limited source data may return incomplete venue or organiser fields.