Skip to content
ChessOS
Start free

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/tournaments

JavaScript

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=8 upcoming events and tournaments
  • /embed/standings/<tournament> a tournament's standings (add ?section=name for one section)
  • /embed/pairings/<tournament>?round=3 one round's pairings (the latest round unless ?round=N is given)
  • /embed/grand-prix/<season> a Grand Prix season's table
  • /embed/shared-calendar shared calendar of followed clubs (month or list; add ?view=list or ?month=2026-12)
  • /embed/shared-events?limit=8 a plain list of the events from followed clubs
  • /embed/shared-clubs a 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.

  • GET/v1/club
    Club

    The 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"
  • GET/v1/events
    Events

    The 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
  • GET/v1/tournaments
    Tournaments

    Published 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"
  • GET/v1/tournaments/{slug}
    Tournament

    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"
  • GET/v1/tournaments/{slug}/sections/{sectionId}
    Section standings, crosstable, pairings and results

    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"

Download the OpenAPI document (JSON)

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.