# Vesus — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Discover upcoming chess tournaments and access detailed information about events including venues, prize pools, organizers, and competition formats like time controls and round structures. Plan your chess competition calendar by browsing tournament listings and reviewing specific event details from vesus.org.

**Category:** Sports | **Website:** [vesus.org/?eventsFilter=%7B%22events%22%3A%7B%22timing%22%3A%22FUTURE%22%7D%7D](https://vesus.org/?eventsFilter=%7B%22events%22%3A%7B%22timing%22%3A%22FUTURE%22%7D%7D) | **Docs:** [parse.bot/marketplace/255f2fca-a154-4adb-84cd-6b8102a18452/vesus-org-api](https://parse.bot/marketplace/255f2fca-a154-4adb-84cd-6b8102a18452/vesus-org-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-vesus-org-api-255f2fca/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_event

Get full details for a specific event by its short key. Returns venue, prize money, organiser, contact details, regulation info, country/region data, and the list of tournaments within the event.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `short_key` | string | Yes | The event's short key identifier (e.g. '827oka8r'). Obtained from get_tournament response event_short_key field. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vesus-org-api-255f2fca/get_event \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"short_key":"<string>"}'
```

### get_tournament

Get detailed tournament configuration including time control periods, rounds, schedule, arbiters, and federation affiliation. Returns the tournament's parent event reference.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `short_key` | string | Yes | The tournament's short key identifier (e.g. 'cnw-opsw'). Obtained from list_events response tournaments[].short_key field. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vesus-org-api-255f2fca/get_tournament \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"short_key":"<string>"}'
```

### list_events

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.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `after` | string | No | Cursor for pagination. Use end_cursor from previous response to get next page. |
| `attendance_mode` | string | No | Attendance mode filter. Accepted values: INPERSON, ONLINE. Omit for all. |
| `country_code` | string | No | ISO 3-letter country code to filter events by country (e.g. ITA, DEU, GBR). Omit for all countries. |
| `limit` | integer | No | Number of events per page (max results to return). |
| `location` | string | No | Filter events by location/city name. |
| `name` | string | No | Filter events by name (partial match). |
| `rated` | string | No | Filter by rated status. Pass 'true' for rated tournaments only, 'false' for unrated only. Omit for all. |
| `time_control_type` | string | No | Comma-separated list of time control types to filter by. Accepted values: BLITZ, RAPID, CLASSICAL, STANDARD. Omit for all. |
| `timing` | string | No | Event timing filter. |
| `tournament_type` | string | No | Tournament type filter. Accepted values: INDIVIDUAL, TEAM. Omit for all. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vesus-org-api-255f2fca/list_events \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"after":"<string>","attendance_mode":"<string>","country_code":"<string>","limit":"<integer>","location":"<string>","name":"<string>","rated":"<string>","time_control_type":"<string>","timing":"<string>","tournament_type":"<string>"}'
```