{"openapi":"3.0.0","tags":[{"name":"organizer"},{"name":"match"},{"name":"organizer_matches"},{"name":"match_api"}],"info":{"title":"Matches","termsOfService":"https:\/\/developer.toornament.com\/terms-guidelines","version":"2.5.1","description":"The Toornament platform connects your website and application with the eSports tournaments around the world.","contact":{"name":"Toornament Developer","url":"https:\/\/developer.toornament.com","email":"contact@toornament.com"}},"servers":[{"url":"https:\/\/api.toornament.com\/organizer\/v2"}],"paths":{"\/matches":{"get":{"tags":["organizer_matches"],"summary":"Retrieves all matches of all your tournaments.","description":"Retrieves the matches of all your tournaments using various filters. If the match type is \u0022ffa\u0022, the opponents are limited by the first 4 ordered by their position.","parameters":[{"$ref":"#\/components\/parameters\/matchRange"},{"$ref":"#\/components\/parameters\/stageIds"},{"$ref":"#\/components\/parameters\/stageNumbers"},{"$ref":"#\/components\/parameters\/groupIds"},{"$ref":"#\/components\/parameters\/groupNumbers"},{"$ref":"#\/components\/parameters\/roundIds"},{"$ref":"#\/components\/parameters\/roundNumbers"},{"$ref":"#\/components\/parameters\/statuses"},{"$ref":"#\/components\/parameters\/isScheduled"},{"$ref":"#\/components\/parameters\/scheduledBefore"},{"$ref":"#\/components\/parameters\/scheduledAfter"},{"$ref":"#\/components\/parameters\/playedBefore"},{"$ref":"#\/components\/parameters\/playedAfter"},{"$ref":"#\/components\/parameters\/disciplines"},{"$ref":"#\/components\/parameters\/tournamentIds"},{"$ref":"#\/components\/parameters\/participantIds"},{"$ref":"#\/components\/parameters\/userIds"},{"$ref":"#\/components\/parameters\/teamIds"},{"$ref":"#\/components\/parameters\/customUserIdentifiers"},{"$ref":"#\/components\/parameters\/matchIds"},{"$ref":"#\/components\/parameters\/circuitIds"},{"$ref":"#\/components\/parameters\/circuitSeasons"},{"$ref":"#\/components\/parameters\/circuitRegions"},{"$ref":"#\/components\/parameters\/circuitTiers"},{"$ref":"#\/components\/parameters\/sort"}],"responses":{"206":{"description":"Matches retrieved","content":{"application\/json":{"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/MatchFully"}}}}}},"security":[{"apiKey":[],"oAuth2":["organizer:result"]}]}},"\/matches\/{id}":{"get":{"tags":["organizer_matches"],"summary":"Retrieves a match.","description":"Retrieves a match identified by the given id. If the match type is \u0022ffa\u0022, a match returns a maximum of 100 opponents.","parameters":[{"$ref":"#\/components\/parameters\/id"}],"responses":{"200":{"description":"Match retrieved","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MatchDetailedFully"}}}}},"security":[{"apiKey":[],"oAuth2":["organizer:result"]}]},"patch":{"tags":["organizer_matches"],"summary":"Updates information and outcome of a match.","description":"Updates information and detailed outcome of a match identified by the given id.","parameters":[{"$ref":"#\/components\/parameters\/id"}],"requestBody":{"description":"Update data","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MatchUpdate"}}}},"responses":{"200":{"description":"Success.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MatchDetailedFully"}}}}},"security":[{"apiKey":[],"oAuth2":["organizer:result"]}]}},"\/tournaments\/{tournament_id}\/matches":{"get":{"deprecated":true,"tags":["organizer_matches"],"summary":"Retrieve the matches of a tournament.","description":"Retrieve the matches from the tournament. If the match type is \u0022ffa\u0022, only the first 4 opponents, ordered by position, are listed in each match.","parameters":[{"$ref":"#\/components\/parameters\/matchRange"},{"$ref":"#\/components\/parameters\/tournamentId"},{"$ref":"#\/components\/parameters\/stageIds"},{"$ref":"#\/components\/parameters\/groupIds"},{"$ref":"#\/components\/parameters\/roundIds"},{"$ref":"#\/components\/parameters\/statuses"},{"$ref":"#\/components\/parameters\/isScheduled"},{"$ref":"#\/components\/parameters\/scheduledBefore"},{"$ref":"#\/components\/parameters\/scheduledAfter"},{"$ref":"#\/components\/parameters\/participantIds"},{"$ref":"#\/components\/parameters\/customUserIdentifiers"},{"$ref":"#\/components\/parameters\/sort"}],"responses":{"206":{"description":"Matches retrieved","content":{"application\/json":{"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/Match"}}}}}},"security":[{"apiKey":[],"oAuth2":["organizer:result"]}]}},"\/tournaments\/{tournament_id}\/matches\/{id}":{"get":{"deprecated":true,"tags":["organizer_matches"],"summary":"Retrieves a match of a tournament.","description":"Returns the match with the given id. A match is limited to 2 participants in \u201cduel\u201d type, and 100 participants in \u201cffa\u201d type.","parameters":[{"$ref":"#\/components\/parameters\/tournamentId"},{"$ref":"#\/components\/parameters\/id"}],"responses":{"200":{"description":"Match retrieved","content":{"application\/json":{"schema":{"type":"array","items":{"$ref":"#\/components\/schemas\/MatchDetailed"}}}}}},"security":[{"apiKey":[],"oAuth2":["organizer:result"]}]},"patch":{"deprecated":true,"tags":["organizer_matches"],"summary":"Update information and outcome of a match.","description":"Updates information and detailed outcome of a match.","parameters":[{"$ref":"#\/components\/parameters\/tournamentId"},{"$ref":"#\/components\/parameters\/id"}],"requestBody":{"description":"Update data","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MatchUpdate"}}}},"responses":{"200":{"description":"Success.","content":{"application\/json":{"schema":{"$ref":"#\/components\/schemas\/MatchDetailed"}}}}},"security":[{"apiKey":[],"oAuth2":["organizer:result"]}]}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","name":"X-Api-Key","in":"header"},"oAuth2":{"type":"oauth2","description":"Access token with \u0027organizer:result\u0027 scope (see (Authorization)[https:\/\/developer.toornament.com\/v2\/security\/authorization]).","flows":{"clientCredentials":{"tokenUrl":"https:\/\/api.toornament.com\/oauth\/v2\/token","scopes":{"organizer:result":"Grants the ability to edit information and referee results."}},"authorizationCode":{"authorizationUrl":"https:\/\/account.toornament.com\/oauth2\/authorize","tokenUrl":"https:\/\/api.toornament.com\/oauth\/v2\/token","scopes":{"organizer:result":"Grants the ability to edit information and referee results."}}}}},"parameters":{"matchRange":{"name":"Range","in":"header","required":true,"schema":{"type":"string","example":"matches=0-99"},"description":"A range of requested items using the \u0027matches\u0027 unit. The size of the range can not exceed 128. (see [Pagination](https:\/\/developer.toornament.com\/v2\/overview\/pagination))."},"tournamentId":{"name":"tournament_id","in":"path","required":true,"schema":{"type":"string","example":"378426939508809728"},"description":"The id of the tournament you want to retrieve data about."},"tournamentIds":{"name":"tournament_ids","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"string"},"example":"618965416546776434,618975467354349191"},"description":"Only return matches for the given list of tournaments."},"id":{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"The id of the requested match."},"stageIds":{"name":"stage_ids","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"string"},"example":"618965765764577354,618931468547654563"},"description":"One or several stage ids to filter."},"stageNumbers":{"name":"stage_numbers","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"integer"},"example":"1,3"},"description":"One or several stage numbers to filter."},"groupIds":{"name":"group_ids","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"string"},"example":"618965314871946714,618932178746476544"},"description":"One or several group ids to filter."},"groupNumbers":{"name":"group_numbers","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"integer"},"example":"2,4"},"description":"One or several group numbers to filter."},"roundIds":{"name":"round_ids","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"string"},"example":"618943519431786343,618965178941654763"},"description":"One or several round ids to filter."},"roundNumbers":{"name":"round_numbers","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"integer"},"example":"1,2"},"description":"One or several round numbers to filter."},"statuses":{"name":"statuses","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","enum":["pending","running","completed"],"items":{"type":"string"},"example":"pending,running"},"description":"One or several match statuses to filter."},"isScheduled":{"name":"is_scheduled","in":"query","required":false,"schema":{"type":"boolean","enum":[0,1]},"description":"Whether to include scheduled matches."},"scheduledBefore":{"name":"scheduled_before","in":"query","required":false,"schema":{"type":"string","format":"datetime","example":"2015-12-31T00:00:00+00:00"},"description":"A datetime to include all matches scheduled before or at the datetime in RFC 3339 format (combined date, time and utc offset)."},"scheduledAfter":{"name":"scheduled_after","in":"query","required":false,"schema":{"type":"string","format":"datetime","example":"2015-12-31T00:00:00+00:00"},"description":"A datetime to include all matches scheduled after or at the datetime in RFC 3339 format (combined date, time and utc offset)."},"playedBefore":{"name":"played_before","in":"query","required":false,"schema":{"type":"string","format":"datetime","example":"2015-12-31T00:00:00+00:00"},"description":"A datetime to include all matches played before or at the datetime in RFC 3339 format (combined date, time and utc offset)."},"playedAfter":{"name":"played_after","in":"query","required":false,"schema":{"type":"string","format":"datetime","example":"2015-12-31T00:00:00+00:00"},"description":"A datetime to include all matches played after or at the datetime in RFC 3339 format (combined date, time and utc offset)."},"disciplines":{"name":"disciplines","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"string"},"example":"leagueoflegends,fifa19"},"description":"Only return matches for the tournaments with the discipline."},"participantIds":{"name":"participant_ids","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"string"},"example":"618965416546776434,618975467354349191"},"description":"One or several participant ids involved in the matches to filter."},"matchIds":{"name":"match_ids","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"string"},"example":"2468971166855626795,436314459115419242"},"description":"Only return matches for the given list of ids."},"userIds":{"name":"user_ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"example":"475141143408399456,735147043408391234"},"description":"One or several player user ids involved in the matches to filter."},"teamIds":{"name":"team_ids","in":"query","required":false,"schema":{"type":"array","items":{"type":"string"},"example":"561714159547269773,255149043401714321"},"description":"One or several team ids involved in the matches to filter."},"customUserIdentifiers":{"name":"custom_user_identifiers","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"string"},"example":"acme:account:1234,acme:account:1235"},"description":"One or several custom user identifiers involved in the matches to filter."},"circuitIds":{"name":"circuit_ids","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"array","items":{"type":"string"},"example":"5617559294676615168,5629045554450325504"},"description":"Only return matches for the given list of circuit ids."},"circuitSeasons":{"name":"circuit_seasons","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"string","example":"season_1,season_3"},"description":"Only return matches for the given list of circuit season machine names."},"circuitRegions":{"name":"circuit_regions","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"string","example":"europe,americas,asia"},"description":"Only return matches for the given list of circuit region machine names."},"circuitTiers":{"name":"circuit_tiers","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"string","example":"tier_1,tier_2"},"description":"Only return matches for the given list of circuit tier machine names."},"sort":{"name":"sort","in":"query","required":false,"explode":false,"style":"form","schema":{"type":"string","enum":["structure","schedule","latest_results"],"example":"schedule","default":"structure"},"description":"A method to sort the filtered data. \u0022structure\u0022 sorts using the stage, group, round and match numbers. \u0022schedule\u0022 sorts using the scheduled date. \u0022latest results\u0022 sorts using the date at which the matches were played (not scheduled)."}},"schemas":{"MatchBase":{"properties":{"settings":{"description":"Settings that describe the various options related to the match.","type":"object"},"scheduled_datetime":{"description":"The scheduled date of the match in RFC 3339 format (combined date, time and utc offset).","type":"string","format":"datetime","nullable":true,"example":"2015-12-31T00:00:00+00:00"},"public_note":{"description":"Public note of a match, written by the organizer for viewers.","type":"string","minLength":1,"maxLength":1500,"nullable":true,"example":"A note for viewers on\\ntwo lines"},"participant_note":{"description":"Participant note of a match, written by the organizer for participants of this match.","type":"string","minLength":1,"maxLength":1500,"nullable":true,"example":"A note for players on\\ntwo lines"},"private_note":{"description":"Private note of a match, written by the organizer for referees.","type":"string","minLength":1,"maxLength":1500,"nullable":true,"example":"A note for referees on\\ntwo lines"}}},"Match":{"allOf":[{"$ref":"#\/components\/schemas\/MatchBase"},{"type":"object","required":["id","stage_id","group_id","round_id","number","type","status","settings","scheduled_datetime","played_at","public_note","participant_note","private_note","report_closed","report_status","opponents"],"properties":{"id":{"description":"The id of the match.","type":"string","example":"618954615761465416"},"status":{"description":"The status of the match.","type":"string","enum":["pending","running","completed"],"example":"pending"},"stage_id":{"description":"The id of the stage that contains this match.","type":"string","example":"618983668512789184"},"group_id":{"description":"The id of the group that contains this match.","type":"string","example":"618985165765456465"},"round_id":{"description":"The id of the round that contains this match.","type":"string","nullable":true,"example":"618965146546456651"},"number":{"description":"The match number (a relative identifier within a round).","type":"integer","example":2},"type":{"description":"The match type.","type":"string","enum":["duel","ffa","bye"],"example":"duel"},"played_at":{"description":"The date and time when the match was completed (a result was provided).","type":"string","format":"datetime","nullable":true,"example":"2015-12-31T00:00:00+00:00"},"report_closed":{"description":"Whether the match report is closed.","type":"boolean","example":true},"report_status":{"type":"string","description":"The report status.","nullable":true,"enum":["report","dispute"],"example":"report"},"opponents":{"type":"array","description":"List of the opponents involved in this match.","items":{"$ref":"#\/components\/schemas\/Opponent"}}}}]},"MatchDetailed":{"allOf":[{"$ref":"#\/components\/schemas\/Match"},{"type":"object","properties":{"opponents":{"type":"array","description":"List of the opponents involved in this match.","items":{"$ref":"#\/components\/schemas\/OpponentDetailed"}}}}]},"MatchFully":{"allOf":[{"$ref":"#\/components\/schemas\/Match"},{"type":"object","required":["id","tournament_id","stage_id","group_id","round_id","number","type","status","settings","scheduled_datetime","played_at","public_note","participant_note","private_note","report_closed","report_status","opponents"],"properties":{"tournament_id":{"description":"The id of the tournament that contains this match.","type":"string","example":"378426939508809728"}}}]},"MatchDetailedFully":{"allOf":[{"$ref":"#\/components\/schemas\/MatchDetailed"},{"type":"object","required":["id","tournament_id","stage_id","group_id","round_id","number","type","status","settings","scheduled_datetime","played_at","public_note","participant_note","private_note","report_closed","report_status","opponents"],"properties":{"tournament_id":{"description":"The id of the tournament that contains this match.","type":"string","example":"378426939508809728"}}}]},"MatchUpdate":{"allOf":[{"$ref":"#\/components\/schemas\/MatchBase"},{"type":"object","properties":{"opponents":{"type":"array","description":"List of the opponents involved in this match.","items":{"$ref":"#\/components\/schemas\/OpponentUpdate"}}}}]},"OpponentBase":{"type":"object","properties":{"number":{"description":"The match opponent number (a relative identifier within a match).","type":"integer","example":1},"position":{"description":"The match opponent position (calculate by internal processes).","type":"integer","readOnly":true,"example":1},"result":{"description":"The match result of the opponent.","type":"string","enum":["win","draw","loss"],"nullable":true,"example":"win"},"rank":{"description":"The match rank of the opponent.","type":"integer","nullable":true,"example":3},"forfeit":{"description":"Whether the opponent is forfeit.","type":"boolean","example":false},"score":{"description":"The score of the opponent.","type":"integer","nullable":true,"example":15}}},"Opponent":{"allOf":[{"$ref":"#\/components\/schemas\/OpponentBase"},{"type":"object","required":["number","position","result","rank","forfeit","score","participant"],"properties":{"participant":{"allOf":[{"$ref":"#\/components\/schemas\/Participant"},{"type":"object","description":"The participant identified with this opponent.","nullable":true}]}}}]},"OpponentDetailed":{"allOf":[{"$ref":"#\/components\/schemas\/Opponent"},{"type":"object","required":["properties"],"properties":{"properties":{"description":"Features of the game played by the opponent.","type":"object"}}}]},"OpponentUpdate":{"allOf":[{"$ref":"#\/components\/schemas\/OpponentBase"},{"type":"object","required":["number"],"properties":{"properties":{"description":"Features of the game played by the opponent.","type":"object"}}}]},"Participant":{"type":"object","nullable":true,"required":["id","name","custom_user_identifier","custom_fields"],"properties":{"id":{"description":"The id of the participant.","type":"string","example":"375143143408309123"},"name":{"description":"The name of the participant.","maxLength":40,"type":"string","example":"Northmen"},"custom_user_identifier":{"description":"An external custom user identifier. Use the format that suits your needs.","type":"string","maxLength":100,"nullable":true,"example":"acme:account:1234"},"custom_fields":{"description":"The values of the custom fields configured in the tournament using the machine names as keys. For more information, please read the [Custom Fields](https:\/\/developer.toornament.com\/v2\/core-concepts\/custom-fields) documentation.","type":"object"}}}}}}