Lovat API
The Lovat API gives your team programmatic access to everything the apps can show you, within the scopes of your key. The current version is /v2. The reference lists every route.
https://api.lovat.cjcameron.com/v2Keys belong to a team, not a person. Anyone on the team can create one in Dashboard → Settings → API keys, with no request process. Team admins can see and revoke every key, and each key has a usage page.
Send the key as a bearer token:
curl https://api.lovat.cjcameron.com/v2/key \ -H "Authorization: Bearer lvt_…"GET /v2/key returns the key’s team and scopes. It’s a cheap way to check that a key works.
Scopes
Section titled “Scopes”Each key has one or more scopes. A route that needs a scope the key doesn’t have returns 403 and names the missing scope.
| Scope | What it covers |
|---|---|
reference:read | Teams, events, matches and official results |
own:read | Your team’s raw reports, scouters, shifts and picklists |
own:write | Uploading reports, creating scouters, marking teams picked |
shared:read | Aggregates from every source team: event and season analysis, predictions, alliances, picklist rankings |
The CSV exports need both own:read and shared:read.
Rate limits
Section titled “Rate limits”Every route has a declared cost, and every key has a token bucket per scope. Each response carries the standard headers, so clients can slow down before they hit the limit:
RateLimit-Policy: "shared:read";q=240;w=120RateLimit: "shared:read";r=236;t=2When a bucket is empty the API returns 429 with a Retry-After header.
The breadth budget
Section titled “The breadth budget”Shared data is also limited by how much of it your team looks at, not just how fast. Each team gets a daily budget of distinct team×event pairs at events your team didn’t attend. This applies across every channel: API keys and Dashboard sessions draw from the same budget.
- Aggregates at your team’s events (registered in Lovat, or on the event’s team list) are unlimited, and so are the per-event CSV exports.
- Other events count toward the budget. Going over returns
429with the reason, never truncated data. - Season-wide bulk access to shared data isn’t offered.
- Your own team’s raw data and public reference data are unlimited.
Sources
Section titled “Sources”Analysis routes take an optional sources parameter: a JSON rule that picks which source teams’ data is merged, for example {"mode":"EXCLUDE","items":[1234]}. Without it, every source is used.
Coming from /v1
Section titled “Coming from /v1”/v1 keeps working for a short overlap, and every response says when it ends. See Migrating from /v1.