# ChessReg

> Online registration for chess tournaments. Parents and coaches register players
> for events, pay via PayPal, and tournament directors manage rosters.

## For AI agents registering a player

A typical task: "Register <player> for <tournament name>". The recommended flow:

1. **Find the event.** `GET /api/v/1/tournaments` (JSON, `Accept: application/json`)
   lists all published events with name, date, fee, available spots, registration
   cutoff, and the event page URL.
2. **Get registration metadata.** `GET /api/v/1/tournaments/{slug-or-id}/registration-options`
   returns everything needed to prepare a registration: sections (with allowed
   grade ids and remaining capacity), grades, fees and upcoming price increases,
   feature flags (schools, USCF teams, ratings databases, shipping addresses),
   school/USCF-team entry types, and optional products. If `registration_open` is
   false or `full` is true, tell the user instead of proceeding.
3. **Look up the player's ratings ids.** `GET /api/v/1/ratings/{eventId}?term={name}`
   searches the event's enabled ratings databases (NWSRS and/or USCF) and returns
   ids, ratings, grade, and school code to prefill the form.
4. **Register via the website.** Registration itself is a multi-step HTML form flow
   starting with a POST to `/register/{eventId}` from the event page. Important:
   - The register button's hidden `homepage` input is a honeypot. It MUST remain
     empty; filling it silently rejects the registration.
   - The flow is session-based: keep cookies, follow redirects (POST-REDIRECT-GET),
     and include the CSRF token like a normal browser would.
   - Carts expire after about an hour; capacity is re-checked when each player is
     added.
5. **Payment is human-only.** The final step uses PayPal. Hand control to the user
   to review the order and pay. Never enter payment credentials on a user's behalf.

## API

- [API documentation](/webservice-api-v1-documentation): human-readable docs for all
  JSON endpoints (tournaments, roster, registration-options, ratings search, schools).
- Rate limit: 100 requests per 30 seconds per IP. Send `Accept: application/json`.

## Other

- Event pages embed schema.org Event JSON-LD, including offers and a RegisterAction.
- Rosters: `GET /api/v/1/tournaments/{slug-or-id}/roster`.