---
title: "Discover open matches"
method: POST
path: "/matches/discover"
tags: ["Match Discovery"]
---

# Discover open matches

`POST /matches/discover`

Returns published pending open matches. League matches are excluded unless leagueId is provided. gameId and gameSlug are mutually exclusive. Requires matches.public_matches:read.

## Request body

- MatchDiscoverBody — Filters and cursor pagination for public open-match discovery.
  - `gameId` string
  - `gameSlug` string
  - `platform` 'PC' | 'XBOX' | 'PLAYSTATION' | 'CONSOLE_ONLY' | 'CROSSPLAY'
  - `region` 'NONE' | 'NA_EAST' | 'NA_WEST' | 'EU' | 'ASIA' | 'OCEANIA' | 'SOUTH_AMERICA' | 'MIDDLE_EAST' | 'AFRICA'
  - `matchType` 'XP_ONLY' | 'WAGER'
  - `scheduledAfter` string
  - `scheduledBefore` string
  - `leagueId` string
  - `leagueSeasonId` string
  - `limit` integer
  - `cursor` string, nullable

## Response `200`

Discoverable open matches.

- MatchDiscoverPage — SP-2 open-match discovery page.
  - `data` ApiMatchDetail[], required
    - `id` string, required
    - `status` 'PENDING' | 'ACCEPTED' | 'READY' | 'IN_PROGRESS' | 'COMPLETED' | 'CANCELLED' | 'DISPUTED' | 'FORFEITED', required — Lifecycle status of a match.
    - `publishStatus` string, required
    - `game` Game, required — Game definition.
      - `id` string, required — Game ID.
      - `nameKey` string, required — Game name key for i18n lookup.
    - `gameMode` string, required
    - `matchType` string, nullable
    - `platform` string, nullable
    - `region` string, nullable
    - `creatorTeam` ApiMatchTeam, required — Team summary embedded in SP-2 match reads.
      - `id` string, required — Team ID.
      - `name` string, required — Team name.
      - `tag` string, required — Team tag (short identifier).
      - `avatarUrl` string, nullable — Team avatar URL.
      - `score` integer, nullable
    - `acceptedTeam` ApiMatchTeam, required — Team summary embedded in SP-2 match reads.
      - `id` string, required — Team ID.
      - `name` string, required — Team name.
      - `tag` string, required — Team tag (short identifier).
      - `avatarUrl` string, nullable — Team avatar URL.
      - `score` integer, nullable
    - `challengedTeam` ApiMatchTeam — Team summary embedded in SP-2 match reads.
      - `id` string, required — Team ID.
      - `name` string, required — Team name.
      - `tag` string, required — Team tag (short identifier).
      - `avatarUrl` string, nullable — Team avatar URL.
      - `score` integer, nullable
    - `bestOf` integer, required
    - `teamSize` integer, required
    - `selectedMaps` string[], required
    - `selectedObjectives` string[], required
    - `winnerTeamId` string, nullable, required
    - `scheduledAt` string, nullable, required
    - `startedAt` string, nullable, required
    - `completedAt` string, nullable, required
    - `createdAt` string, nullable, required
    - `leagueId` string, nullable
    - `leagueSeasonId` string, nullable
  - `nextCursor` string, nullable, required
  - `hasMore` boolean, required
  - `timestamp` string, required

## Other responses

- `400` — Bad request (invalid body, cursor, limit, or date).
- `401` — Missing or invalid API key.
- `403` — API key lacks the required permission.
- `404` — Resource not found.
- `429` — Rate limited.
- `500` — Internal server error.

---

[API](https://skmtc.net/teambattles/apis/teambattles-api.md) · [All operations](https://skmtc.net/teambattles/apis/teambattles-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/teambattles/teambattles-api/versions/2ffe8fb53b7d/schema)