ChessOS API
Read your club's public events and tournament results from your own website, scoreboard or app.
Authentication
Club officers create a read-only token in ChessOS Organizer under Settings > API access. Send it in an Authorization: Bearer header on every request. A token is shown once, can be renamed, rotated or revoked at any time, and reads only its own club.
Tokens are scoped to events, tournaments or both. They can never read members, contact details, dates of birth, guardians or anything a club has not published.
Examples
curl
curl -H "Authorization: Bearer $CHESSOS_TOKEN" \n https://api.chesscrossing.com/v1/tournamentsJavaScript
const response = await fetch("https://api.chesscrossing.com/v1/tournaments", {
headers: { Authorization: `Bearer ${process.env.CHESSOS_TOKEN}` },
});
if (!response.ok) throw new Error(`ChessOS API ${response.status}`);
const { tournaments } = await response.json();Embed widgets
A club can show its live events, standings, pairings and Grand Prix table on any website that accepts HTML, with no token. Officers copy a ready snippet from Organizer under Website > Settings > Embed.
<iframe src="https://YOURCLUB.chessos.club/embed/standings/spring-open" title="Standings" style="width:100%;border:0;min-height:480px" loading="lazy"></iframe>Or use the script, which sizes the frame to its content:
<div data-chessos-embed="https://YOURCLUB.chessos.club/embed/events?limit=8"></div>
<script async src="https://YOURCLUB.chessos.club/embed.js"></script>/embed/events?limit=8upcoming events and tournaments/embed/standings/<tournament>a tournament's standings (add ?section=name for one section)/embed/pairings/<tournament>?round=3one round's pairings (the latest round unless ?round=N is given)/embed/grand-prix/<season>a Grand Prix season's table/embed/shared-calendarshared calendar of followed clubs (month or list; add ?view=list or ?month=2026-12)/embed/shared-events?limit=8a plain list of the events from followed clubs/embed/shared-clubsa directory of the clubs this club follows
Paste the snippet into any page that accepts HTML. Names follow each tournament's privacy settings, as on the public pages.
Rate limits
Each token has its own limit, 60 requests a minute by default (officers can set 1 to 600). Over the limit you get 429 with a Retry-After header; X-RateLimit-Limit and X-RateLimit-Remaining show your allowance. Answers may be cached for 15 seconds.
Tokens are for a club's own tools. Copying public data in bulk is still covered by our anti-scraping rules, and repeated failed token attempts from one address are blocked for a while.
Reference
Generated from the API itself, so it stays in English. Only the /v1 endpoints are listed.
- GETClub
/v1/clubThe club's public name, time zone and website, and the scopes of this token.
Response fields
- name: string
- timezone: string
- siteUrl: string
- scopes[]: "events" | "tournaments"
- GETEvents
/v1/eventsThe club's public events and club meetings, as listed on its website. Needs the 'events' scope.
Response fields
- events[].event.id: string (uuid)
- events[].event.kind: "club_meeting" | "casual_tournament" | "social" | "class" | "lecture" | "camp" | "simul" | "scholastic" | "blitz_rapid" | "quads" | "bughouse" | "chess960" | "online" | "other"
- events[].event.title: string
- events[].event.description: string
- events[].event.startTime: string
- events[].event.endTime: string
- events[].event.recurrence: object | object | object | object | object
- events[].event.startsOn: string (date)
- events[].event.cost: string
- events[].event.visitorInfo: string
- events[].event.beginnerFriendly: boolean
- events[].event.timezone: string
- events[].venue.name: string
- events[].venue.street: string
- events[].venue.city: string
- events[].venue.region: string
- events[].venue.postalCode: string
- events[].venue.directions: string
- events[].venue.latitude: number
- events[].venue.longitude: number
- GETTournaments
/v1/tournamentsPublished and finished tournaments, newest first. Drafts are never listed. Needs the 'tournaments' scope.
Response fields
- tournaments[].id: string (uuid)
- tournaments[].slug: string
- tournaments[].title: string
- tournaments[].startsOn: string
- tournaments[].endsOn: string
- tournaments[].status: "published" | "finished"
- GETTournament
/v1/tournaments/{slug}One published tournament: venue, schedule, sections, prizes and the entry list when the organizer shows it. Needs the 'tournaments' scope.
Path: slug
Response fields
- id: string (uuid)
- title: string
- slug: string
- startsOn: string (date)
- endsOn: string (date)
- venue.name: string
- venue.address: string
- venue.directions: string
- venue.latitude: number
- venue.longitude: number
- venue.street: string
- venue.city: string
- venue.region: string
- venue.postalCode: string
- description: string
- schedule: string
- ratingType: "regular" | "quick" | "blitz" | "dual" | "unrated"
- variant: "standard" | "chess960" | "bughouse"
- variantLabel: string
- startingPositions[].round: integer
- startingPositions[].position: integer
- startingPositions[].source: "drawn" | "chosen" | "corrected" | "earlier"
- startingPositions[].by: "system" | "organizer" | "chief_td"
- startingPositions[].at: string (date-time)
- startingPositions[].reason: string
- startingPositions[].replaced[].position: integer
- startingPositions[].replaced[].source: "drawn" | "chosen" | "corrected" | "earlier"
- startingPositions[].replaced[].at: string (date-time)
- registrationOpen: boolean
- entryFees[].label: string
- entryFees[].cents: integer
- entryFees[].until: string (date)
- entryFees[].sectionId: string (uuid)
- refundPolicy: string
- prizes[].name: string
- prizes[].cents: integer
- prizes[].item: string
- prizes[].eligible: string
- prizes[].sectionId: string (uuid)
- prizes[].place: integer
- prizes[].ratingUnder: integer
- gamePolicy: string
- sections[].id: string (uuid)
- sections[].name: string
- sections[].format: "swiss" | "round_robin" | "quads" | "octads" | "elimination_single" | "elimination_double"
- sections[].rounds: integer
- sections[].timeControl: string
- sections[].ratingUnder: integer
- sections[].unratedAllowed: boolean
- sections[].capacity: integer
- sections[].entries: integer
- sections[].roundsPaired: integer
- sections[].registrationOpen: boolean
- sections[].ratingText: string
- sections[].ratingMin: integer
- sections[].ratingMax: integer
- sections[].outsideRating: "block" | "warn" | "play_up"
- sections[].playUpFeeCents: integer
- sections[].ratingSources[]: "us_chess_regular" | "us_chess_quick" | "us_chess_blitz" | "club" | "fide" | "self_reported"
- sections[].payLater: "off" | "deadline" | "door"
- GETSection standings, crosstable, pairings and results
/v1/tournaments/{slug}/sections/{sectionId}A section's rounds with boards and results, standings and crosstable. Rounds held back until their date are not shown. Needs the 'tournaments' scope.
Path: slug, sectionId
Response fields
- section.id: string (uuid)
- section.name: string
- section.format: "swiss" | "round_robin" | "quads" | "octads" | "elimination_single" | "elimination_double"
- section.rounds: integer
- section.timeControl: string
- section.ratingUnder: integer
- section.unratedAllowed: boolean
- section.capacity: integer
- section.registrationOpen: boolean
- section.bracket.thirdPlace: boolean
- section.bracket.drawRule: "replay" | "armageddon"
- section.rules.ratingMin: integer
- section.rules.ratingMax: integer
- section.rules.outsideRating: "block" | "warn" | "play_up"
- section.rules.playUpFeeCents: integer
- section.rules.ratingSources[]: "us_chess_regular" | "us_chess_quick" | "us_chess_blitz" | "club" | "fide" | "self_reported"
- section.rules.usChessCheck: "off" | "warn" | "email" | "block"
- section.rules.payLater: "off" | "deadline" | "door"
- section.rules.payBy: string (date)
- section.rules.releaseUnpaid: boolean
- section.entries: integer
- section.roundsPaired: integer
- currentRound: integer
- rounds[].round: integer
- rounds[].complete: boolean
- rounds[].boards[].board: integer
- rounds[].boards[].white: object
- rounds[].boards[].black: object
- rounds[].boards[].result: "1-0" | "0-1" | "1/2-1/2" | "1F-0F" | "0F-1F" | "0F-0F"
- rounds[].boards[].postponed: boolean
- rounds[].boards[].playedOn: string (date)
- rounds[].date: string (date)
- rounds[].startingPosition: integer
- rounds[].hidden: boolean
- rounds[].out[].name: string
- rounds[].out[].halfPoints: integer
- rounds[].out[].why: string
- rounds[].signoff.kind: "pair" | "repair" | "unpair" | "house_game" | "merge"
- rounds[].signoff.byName: string
- rounds[].signoff.role: "chief" | "assistant" | "section_chief"
- rounds[].signoff.at: string (date-time)
- standings[].place: string
- standings[].id: string
- standings[].name: string
- standings[].rating: integer
- standings[].score: integer
- standings[].tiebreaks: object
- standings[].flag: "house" | "expelled"
- tiebreakNames[].key: string
- tiebreakNames[].label: string
- log[].seq: integer
- log[].summary: string
- log[].actor: string
- log[].reason: string
- log[].at: string (date-time)
- blocked: string
- td.settings.pairingSystem: "us_chess" | "monrad" | "danish"
- td.settings.acceleration: "none" | "added_score" | "adjusted_rating" | "sixths" | "baku"
- td.settings.danishSeed: integer
- td.settings.octadPlay: "round_robin" | "swiss"
Terms
Use the API for a club's own sites and tools. Do not resell the data, build a competing directory from it or collect it in bulk, and do not try to read anything a token does not grant. We may limit or revoke tokens that break these terms. This is a plain-language note; the full terms of service apply.
Changelog
- 1.0.0 (2026-10-22)
First release: club, events, tournaments, and per-section standings, crosstables, pairings and results. Read-only, per-club tokens.