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

Keys

Keys belong to a team, not a person. Anyone on the team can create one in Lovat Dashboard under Settings → API keys, with no request process:

1. Select New key, give it a name you’ll recognize later, like “Strategy spreadsheet”, and choose its Access (the scopes below).
2. Select Create key and copy the key. This is the only time Lovat shows it, so store it somewhere safe.

Scouting leads can see and revoke every key on the team; analysts see and revoke the keys they created. Each key’s Usage page shows its requests, cost and rejected requests by day and by route over the last 7, 30 or 90 days. Revoke a key from its menu if it leaks.

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

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	In Dashboard	What it covers
reference:read	Reference data	Teams, events, matches and official results
own:read	Read your team’s data	Your team’s raw reports, scouters, shifts and picklists
own:write	Change your team’s data	Uploading reports, creating scouters, marking teams picked
shared:read	Shared aggregates	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

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=120
RateLimit: "shared:read";r=236;t=2

When a bucket is empty the API returns 429 with a Retry-After header.

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 (events your team is on the team list for or has scouted) are unlimited, and so are the per-event CSV exports.
• Other events count toward the budget. Going over returns 429 with 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

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

/v1 keeps working for a short overlap, and every response says when it ends. See Migrating from /v1.