API Documentation

Last updated November 11, 2026

The OWTV.gg API gives you programmatic access to match, team, player and tournament data. The documentation is public. A key is required to make requests, and keys are available to supporters on our Patreon. Use of the API is covered by our Terms of Service.

Overview

The API is a REST API that returns JSON. Every collection is available at the same base URL:

https://owtv.gg/api/<collection>

The schema can change while the API is in early access. Breaking changes are listed in the changelog.

Getting access

API access is included with the supporter tier on our Patreon. To get a key:

Join the API access tier on Patreon.
Request a key by emailing owtvgg@gmail.com or messaging us on Discord.
We create your API client with the scopes and rate limit for your tier and let you know when it is ready.
Generate your key from your API client. It is shown once.

Authentication

Send your key in the X-API-Key header on every request.

curl "https://owtv.gg/api/match?limit=10" \
  -H "X-API-Key: YOUR_KEY"

Keep your key private. Do not put it in client-side code, public repositories or screenshots. We store only a hash of your key, so we cannot recover it. If it leaks or you lose it, ask us to revoke it and generate a new one.

Rate limits

Each key is limited to 60 requests per minute by default. Higher limits can be set per key. When you exceed your limit the API responds with 429 Too Many Requests. Wait for the window to reset before retrying, and cache responses where you can.

Scopes

Each key has one or more scopes. A request to a collection outside your scopes returns 403.

Scope	Allows	Collections
`read:matches`	Read	match, match-map, map-fight, player-map-stats, player-map-stats-hero, game-hero, game-map, hero-perk
`read:teams`	Read	team, team-membership, person
`read:tournaments`	Read	tournament, tournament-phase, tournament-phase-round, tournament-phase-standing, tournament-result, region
`read:fantasy`	Read	Coming soon. Not available yet.

Creating, updating and deleting any collection is not available through the API.

Reading data

Use GET /api/<collection> to list documents and GET /api/<collection>/<id> to fetch one.

Parameter	Example	Notes
`limit`	`limit=20`	Page size. Maximum 100.
`page`	`page=2`	Page number, starting at 1.
`sort`	`sort=-createdAt`	Field to sort by. Prefix with - for descending.
`depth`	`depth=0`	How far to expand related documents. 0 returns IDs only, 1 or 2 embeds them. Embedded data is limited to your scopes.
`where`	`where[complete][equals]=true`	Filter by field. Operators include equals, not_equals, in, greater_than and less_than.

Examples

All completed matches:

curl "https://owtv.gg/api/match?where[complete][equals]=true&limit=20" \
  -H "X-API-Key: YOUR_KEY"

Hero stats for one player on one map, with related data expanded:

curl "https://owtv.gg/api/player-map-stats-hero?where[playerMapStats][equals]=345&depth=1" \
  -H "X-API-Key: YOUR_KEY"

Paginated responses

List requests return docs plus pagination fields: totalDocs, limit, page, totalPages, hasNextPage and hasPrevPage.

Collections

Every document includes id, createdAt and updatedAt.

Teams and people

`team`

A team. Requires read:teams.

Field	Type	Notes
`name`	text	Team name.
`initials`	text	Short name/ initials.
`region`	enum	Region the team is based in.
`tier`	enum	Tier the team generally competes at. Currently unused.
`nationality`	enum	Nationality of the team.
`image`	ID or object	Team logo (media).
`primaryColour`	text	Hex code without #, for example FF0000.
`accentColour`	text	Hex code without #.
`faceitId`	text	Faceit team ID.
`facebookUrl`	text	URL
`twitterUrl`	text	URL
`websiteUrl`	text	Official website URL.
`youtubeUrl`	text	URL
`liquipediaUrl`	text	URL

`person`

A player, coach, analyst, content creator or other person in the scene. Requires read:teams.

Field	Type	Notes
`alias`	text	Gamer tag.
`name`	text	Legal name. Often empty or same as alias.
`job`	enum	The job associated with this person.
`playerRole`	enum	Player role. Empty for non-players.
`region`	enum	Region the person plays or works in.
`nationality`	enum	Nationality.
`cachedTeam`	ID[] (team)	Current team or teams. Updated automatically from team-membership.
`faceitId`	text	Faceit ID.
`gameId`	text	Game-specific ID.
`imageUrl`	text	Image URL.
`facebookUrl`	text	URL
`twitterUrl`	text	URL
`websiteUrl`	text	URL
`youtubeUrl`	text	URL
`liquipediaUrl`	text	URL

`team-membership`

Which person was on which team, in which role, and when. Requires read:teams.

Field	Type	Notes
`team`	ID (team)
`person`	ID (person)
`job`	enum	Job on the team.
`playerRole`	enum	Role on the team. Empty for non-players.
`joinedDate`	date	When the person joined.
`departedDate`	date	When the person left. Empty if they are still on the team.

Tournaments

`region`

A competitive region. Requires read:tournaments.

Field	Type	Notes
`name`	text	Display name, for example Europe.
`slug`	text	Identifier, for example eu.
`color`	text	Hex colour including #.
`logo`	ID or object	Region logo or flag (media).

`tournament`

A tournament. Requires read:tournaments.

Field	Type	Notes
`name`	text
`slug`	text	URL-safe name, up to 40 characters.
`description`	text
`information`	JSON	Rich text content in Lexical JSON format.
`regions`	ID[] (region)	Regions the tournament is played in.
`tier`	enum	Tournament tier. Not currently used.
`startDate`	date
`endDate`	date
`format`	online \| lan
`location`	text	City and country of the venue. LAN only.
`venue`	text	Venue name. LAN only.
`countryCode`	text	ISO 3166-1 alpha-2 code, for example KR. LAN only.
`mapPool`	ID[] (game-map)	Maps available in the tournament.
`hasDrops`	boolean	Whether drops are enabled.
`image`	ID or object	Tournament image (media).
`phases`	join	Read-only list of tournament-phase documents.
`results`	join	Read-only list of tournament-result documents.

`tournament-phase`

A stage of a tournament, such as groups or playoffs. Requires read:tournaments.

Field	Type	Notes
`title`	text	Generated. Tournament name and phase name.
`tournament`	ID (tournament)
`name`	text	For example Groups or Playoffs.
`type`	enum	Phase format.
`description`	text
`startDate`	date
`endDate`	date
`carryOverFrom`	ID (tournament-phase)	Phase whose standings carry into this one.
`mapPoolOverride`	ID[] (game-map)	Replaces the tournament map pool for this phase. Empty means inherit.
`rounds`	join	Read-only list of tournament-phase-round documents.
`matches`	join	Read-only list of match documents.
`standings`	join	Read-only list of tournament-phase-standing documents.

`tournament-phase-round`

A round within a phase. Requires read:tournaments.

Field	Type	Notes
`tournamentPhase`	ID (tournament-phase)
`name`	text	For example Week 1 or Round of 16.
`order`	number	Display order.

`tournament-phase-standing`

A team's standing within a phase. Requires read:tournaments.

Field	Type	Notes
`tournamentPhase`	ID (tournament-phase)
`team`	ID (team)
`seed`	number	Entry seeding. Set on the first phase of a tournament.
`groupNumber`	number	Group within the phase, if there are groups.
`cachedGamesPlayed`	number	Matches played.
`cachedGamesWon`	number	Matches won.
`cachedGamesLossed`	number	Matches lost.
`cachedGamesDrew`	number	Matches drawn.
`cachedMapsPlayed`	number	Maps played.
`cachedMapsWon`	number	Maps won.
`cachedMapsLossed`	number	Maps lost.
`cachedMapsDrew`	number	Maps drawn.
`tiebreakerOrder`	number	Manual ordering used to break ties.

`tournament-result`

A final placement in a tournament. Requires read:tournaments.

Field	Type	Notes
`tournament`	ID (tournament)
`team`	ID (team)	Team that achieved the result.
`positionFrom`	number	Start of the placement range, for example 4 for 4th to 5th.
`positionTo`	number	End of the range. Empty for a single position.
`prize`	number	Prize money in USD.
`qualifiesTo`	ID[] (tournament)	Tournaments this placement qualifies the team for.

Matches and stats

`match`

A match between two teams. Scores and winner are generated from its maps. Requires read:matches.

Field	Type	Notes
`tournamentPhase`	ID (tournament-phase)
`round`	ID (tournament-phase-round)
`slug`	text	URL-safe identifier.
`team1`	ID (team)	Empty until the team is decided. See team1Placeholder.
`team2`	ID (team)	Empty until the team is decided. See team2Placeholder.
`team1Placeholder`	text	Label shown while team1 is undecided.
`team2Placeholder`	text	Label shown while team2 is undecided.
`team1Score`	number	Maps won by team 1.
`team2Score`	number	Maps won by team 2.
`winningTeam`	ID (team)
`resultType`	enum	How the match ended: normal play, forfeit or disqualification.
`startDate`	date	Scheduled start time.
`complete`	boolean	Whether the match has concluded.
`firstTo`	number	Map wins needed. 2 for a Bo3, 3 for a Bo5.
`regions`	ID[] (region)	Generated from the tournament.
`maps`	join	Read-only list of match-map documents.
`cachedTeam1Votes`	number	Generated from supporter votes.
`cachedTeam2Votes`	number	Generated from supporter votes.
`previousSlugs`	array	Objects with a slug field. Old slugs for redirects.
`bracketMatchNumber`	number	Match number within the bracket.
`bracketGroup`	text	Group label when a phase has parallel brackets.
`bracketSide`	enum	winners, losers, grand_final, third_place, seeding, main or fifth_place.
`nextMatchWinner`	ID (match)	Match the winner advances to.
`nextMatchWinnerSlot`	team1 \| team2	Slot the winner fills.
`nextMatchLoser`	ID (match)	Match the loser drops to. Double elimination.
`nextMatchLoserSlot`	team1 \| team2	Slot the loser fills.
`qualifiesWinnerToPhase`	ID (tournament-phase)	Phase the winner advances to.
`qualifiesWinnerToPhaseLabel`	text	Custom label for the winner's qualification.
`qualifiesLoserToPhase`	ID (tournament-phase)	Phase the loser advances to.
`qualifiesLoserToPhaseLabel`	text	Custom label for the loser's qualification.

`match-map`

A single map played within a match. Requires read:matches.

Field	Type	Notes
`match`	ID (match)	Parent match.
`map`	ID (game-map)
`mapIndex`	number	Position of the map in the match.
`slug`	text	URL-safe identifier.
`team1Score`	number	Score for team 1.
`team2Score`	number	Score for team 2.
`winningTeam`	ID (team)
`complete`	boolean	Whether the map has concluded.
`resultType`	enum	How the map ended: normal play, forfeit or disqualification.
`blueTeam`	ID (team)	Team on blue side. Used for advanced stats.
`redTeam`	ID (team)	Team on red side. Used for advanced stats.
`mapPickerType`	enum	How the map was chosen.
`mapPicker`	ID (team)	Team that picked the map.
`firstBan`	ID (team)	Team with the first ban.
`team1Ban`	ID (game-hero)	Hero banned by team 1.
`team2Ban`	ID (game-hero)	Hero banned by team 2.
`oneVsOneWinner`	ID (team)	Winner of the 1v1 that decides picks. OWWC Format.
`winnerChoice`	map \| banOrder	What the 1v1 winner chose.
`banOrderChoice`	first \| second	Ban order chosen.
`replayCode`	text	Replay code, up to 12 characters.
`replayParsed`	text	Replay parsing status.
`eventLog`	JSON	Raw map event log.
`playerStats`	join	Read-only list of player-map-stats documents.

`map-fight`

A team fight within a map. Requires read:matches.

Field	Type	Notes
`matchMap`	ID (match-map)
`fightNumber`	number	Fight order within the map, from 1.
`fightStartTime`	number	Seconds from map start. 0 or more.
`fightLength`	number	Seconds.
`winningTeam`	ID (team)	Empty if the fight had no winner.
`losingTeam`	ID (team)	Empty if the fight had no loser.
`team1Kills`	number
`team2Kills`	number
`team1Deaths`	number
`team2Deaths`	number
`team1Ults`	array	Objects with a hero ID. One per ultimate used.
`team2Ults`	array	Objects with a hero ID. One per ultimate used.
`eventLog`	JSON	Raw fight event log.

`player-map-stats`

A player's stat line for one map. Requires read:matches.

Field	Type	Notes
`matchMap`	ID (match-map)
`team`	ID (team)
`person`	ID (person)
`role`	enum	Role played on this map.
`eliminations`	number
`assists`	number
`deaths`	number
`damageDealt`	number
`healingDone`	number
`damageMitigated`	number
`cachedFantasyScore`	number	Generated fantasy score.
`matchStartDate`	date	Generated from the match.
`heroStats`	join	Read-only list of player-map-stats-hero documents, longest playtime first.

`player-map-stats-hero`

A player's stats on one hero within a map. Requires read:matches.

Field	Type	Notes
`playerMapStats`	ID (player-map-stats)
`hero`	ID (game-hero)
`playtime`	number	Seconds.
`totalElims`	number
`totalAssists`	number
`totalDeaths`	number
`totalDmg`	number	Damage dealt.
`totalHeal`	number	Healing done.
`totalMit`	number	Damage mitigated.
`fightsTotal`	number	Fights played on this hero.
`totalUltsUsed`	number
`totalUltChargeTime`	number	Seconds.
`minorPerks`	ID[] (hero-perk)
`majorPerks`	ID[] (hero-perk)

Game data

`game-hero`

A hero. Use these IDs in stats payloads. Requires read:matches.

Field	Type	Notes
`name`	text
`gameRole`	enum	Tank, damage or support.
`gameId`	text	Internal game identifier.
`faceitId`	text	Faceit hero ID.
`image`	ID or object	Hero image (media).

`game-map`

A map. Requires read:matches.

Field	Type	Notes
`name`	text
`mode`	enum	Game mode.
`gameId`	text	Internal game identifier.
`image`	ID or object	Map image (media).

`hero-perk`

A minor or major perk for a hero. Requires read:matches.

Field	Type	Notes
`name`	text
`hero`	ID (game-hero)	Hero the perk belongs to.
`perkType`	enum	Minor or major.
`active`	boolean	Whether the perk is currently in the game.
`releasedAt`	date	Release date.
`sunsetAt`	date	Date the perk was removed. Never before releasedAt.

Errors

Status	Meaning	What to do
`400`	The body or query failed validation.	Check field names, types and required fields.
`401`	The key is missing, invalid or revoked.	Check the X-API-Key header.
`403`	Your key lacks the scope, or a field is not writable.	Check your scopes and the writable fields above.
`404`	The collection or document does not exist.	Check the collection name and ID.
`429`	You exceeded your rate limit.	Wait for the next 60 second window.

Error responses are JSON:

{
  "errors": [{ "message": "Forbidden: field not writable" }]
}

Changelog and support

November 11, 2026. Public documentation published.

Found a bug, need a higher rate limit or want a key revoked? Email owtvgg@gmail.comor message us on Discord .