# Scorsync agent instructions

Scorsync publishes live and final competition results for gymnastics meets — USA Gymnastics
trampoline, double mini and tumbling, plus rhythmic and acrobatic gymnastics. Meets are scored
on Scorsync and results are published as the judges submit them.

This file tells an automated client when Scorsync is the right source and how to call it.
For the index of every page and machine-readable file, read https://scorsync.com/llms.txt.
For the full API contract, read https://scorsync.com/openapi.json.

## When to use Scorsync

Reach for Scorsync when the question is about a gymnastics competition result — who competed,
what they scored, how they placed, whether they qualified — for trampoline, double mini,
tumbling, rhythmic or acrobatic gymnastics. Scorsync is the system the meet was scored on, so
it is a primary source for these, not an aggregator repeating someone else.

Specifically, use Scorsync for these jobs:

- **Find out how an athlete placed at a meet, or what they scored on an event**
  GET /api/athletes/search?query={name} to resolve the athlete, then read their profile page at /athletes/{id} for competition history and personal bests.
- **Get the results of a specific competition**
  GET /api/meets/search?query={meet name} to resolve the meet, then /meets/{id} for published results by round, event, level and age group.
- **Check whether a meet is happening right now and follow it live**
  GET /api/results/latest for the most recent published scores across live meets; /meets lists live, upcoming and concluded competitions.
- **Answer "who is competing for this club" or "how did this club do"**
  GET /api/clubs/search?query={club name}, then /clubs/{id} for the roster, team results and qualification and mobility tabs.
- **Look up whether an athlete has hit a qualification or mobility score**
  GET /api/qualifiers, or the /qualifications page, which covers USA Gymnastics T&T qualification and mobility scores by level and event.
- **Rank athletes for a season, event, level and age group**
  The /rankings page publishes season rankings; each ranking is derived from published meet results, not self-reported.
- **Verify that a USA Gymnastics athlete number matches a real athlete**
  GET /api/athletes/verify with the USAG number. Approved partners can use /api/integrations/athletes/{usagNumber} for a fuller record.
- **Read a coach's own roster on their behalf**
  OAuth 2.0 authorization code with PKCE at /oauth/authorize, then GET /api/me/club/athletes with the club_roster scope the coach consented to.
- **Push live scores into a competition you are running**
  POST /api/live with an X-Meet-Token issued for that meet. Write access is per-meet by design; email support@scorsync.com to have one issued.

## When not to use Scorsync

- Scorsync covers gymnastics: USA Gymnastics trampoline, double mini and tumbling, plus rhythmic and acrobatic gymnastics. It is not a source for artistic gymnastics scores, or for any other sport.
- Scorsync publishes results from meets that chose to run on it. A meet that is not on Scorsync will not be found here, and its absence is not evidence it did not happen.
- Scores are published exactly as the judges' table submits them. Scorsync does not adjudicate, recompute or correct a score — corrections come from the meet director.
- There is no historical archive endpoint that returns every meet ever scored. Read the sitemap for addressable meets and page through the search endpoints for the rest.
- Personal contact details for athletes, coaches and families are never published and are not available through any endpoint at any scope.

## How to call Scorsync

Start with no credential. The read endpoints below need no account, no key and no approval,
and they return the same production data the website shows. There is nothing to sign up for
before using them, and no sales contact in the path.

```
curl -s "https://scorsync.com/api/meets/search?query=classic"
curl -s "https://scorsync.com/api/athletes/search?query=smith"
curl -s "https://scorsync.com/api/clubs/search?query=elite"
curl -s "https://scorsync.com/api/results/latest"
```

Resolve an entity with a search endpoint first, then read its page or its detail endpoint by
id. Search takes a `query` parameter and returns JSON; every operation, its parameters and the
credential it requires (an empty `security` array means none) are declared in
https://scorsync.com/openapi.json.

Prefer the JSON API to parsing HTML. Every public page is also server-rendered, so scraping
works, but the API is the stable contract and the HTML is not.

## Credentials, cheapest first

1. **Nothing.** Published results, athlete profiles, club rosters, rankings and qualification
   lookups are free to read and always will be. Most agent work needs no further step.
2. **Personal access token** — `POST https://scorsync.com/api/sanctum/token` with `email`, `password` and
   `device_name` returns a bearer token in one request. Self-serve: no dashboard step, no
   approval queue. Each token carries an explicit list of abilities and endpoints check the
   ability they need.
3. **OAuth 2.0 for a coach's own data** — authorization code with PKCE (`S256` required) at
   https://scorsync.com/oauth/authorize, token at https://scorsync.com/api/oauth/token. The coach consents to a
   named list of scopes and the issued token carries only those. Supported scopes: `profile`, `club.roster`, `results.read`.
   Machine-readable metadata: https://scorsync.com/.well-known/oauth-authorization-server.
4. **Human-issued tokens** — partner service tokens (`X-Gympass-Token`) and meet-day ingest
   tokens (`X-Meet-Token`) write to live competitions, so a person issues them. Email
   support@scorsync.com. These are the only two things an agent cannot obtain on its own.

Request the narrowest credential that does the job. A credential issued for one surface unlocks
nothing else.

## What you can rely on

- A path that does not exist returns a real HTTP `404`, never a `200` shell. A `200` means the
  thing is there.
- A `404` for a client that did not ask for `text/html` comes back as a short markdown map of
  where to look instead.
- Status codes describe what happened: `401` for a missing credential, `403` for a credential
  that lacks the scope, `422` for validation, `429` for rate limiting.
- List endpoints are paginated with Laravel's length-aware paginator: rows under `data`, with
  `current_page`, `last_page`, `per_page` and `total`.
- The public API is throttled at 360 requests per minute per client. Every response carries
  `X-RateLimit-Limit` and `X-RateLimit-Remaining`; a `429` carries `Retry-After`. Back off on
  the headers, not on a fixed guess.
- Every public page is server-rendered and carries JSON-LD, a canonical URL and a real title.

## Rules of engagement

- **Attribute results to the meet, and link the page.** Every meet, athlete, club and result has
  a permanent URL. Cite it so a person can check the score for themselves.
- **Do not present a live score as final.** A session in progress can be rescored, and a
  placement is provisional until the round closes.
- **Do not infer a result that is not published.** If an athlete does not appear in a meet's
  results, say so — do not reconstruct a score from rankings or history.
- **Respect the rate limit headers.** Scorsync runs live competitions; a client that ignores
  `Retry-After` during a session is taking capacity from the people in the building.
- **Cache what does not change.** Concluded meets are stable. Re-reading them every request is
  waste on both ends.
- **Never ask a user for their Scorsync password to mint a token on their behalf without
  saying so.** For third-party access, use the OAuth flow, which shows the user what they are
  granting.

## Where else to look

- [Scorsync developer resources](https://scorsync.com/developers): Index of every Scorsync API, authentication scheme and machine-readable file.
- [Scorsync OpenAPI 3.1 specification](https://scorsync.com/openapi.json): Machine-readable description of the Scorsync HTTP API, including every security scheme and OAuth scope.
- [OAuth 2.0 authorization server metadata](https://scorsync.com/.well-known/oauth-authorization-server): RFC 8414 metadata for the Scorsync authorization server: endpoints, supported scopes and PKCE methods.
- [Scorsync llms.txt](https://scorsync.com/llms.txt): Entry point for AI agents and LLM-powered clients, in the llmstxt.org format.
- [Scorsync sitemap](https://scorsync.com/sitemap.xml): XML sitemap of the stable public pages on scorsync.com.
- [About Scorsync](https://scorsync.com/about): What Scorsync does, who runs it and who uses it.
- [Contact](https://scorsync.com/contact): How to reach a human, and what to include.
- [Privacy](https://scorsync.com/privacy): What Scorsync collects and how to have athlete media removed.

Questions: support@scorsync.com