---
title: "Create Tournament API"
method: POST
path: "/v2/tournaments"
---

# Create Tournament API

`POST /v2/tournaments`

Creates a new tournament. Requires an `Idempotency-Key` header: pass a unique string per request; retrying with the same key returns the original response instead of creating a duplicate tournament. Keys are retained for 10 minutes and are scoped per token.

## Headers

- `Idempotency-Key` string, required

## Request body

- TournamentCreateRequest
  - `game_code` string, required — The game to run the tournament on. Use the `code` value from the [All Games API](/publishers/gamezop/types-of-integration/all-games-api). Tournaments can only be created on score-based games enabled for your account — ask your Gamezop Account Manager for your eligible list.
  - `title` string, required — Tournament title. 3 to 100 characters.
  - `starts_at` string, date-time, required — Tournament start time (UTC, ISO 8601). Must be in the future, and no more than 15 days from now.
  - `duration_seconds` integer, required — Tournament duration in seconds. Minimum 300 (5 minutes), maximum 259200 (3 days). `ends_at` is computed as `starts_at` + `duration_seconds`.
  - `max_score_attempts` integer — (Optional) Maximum number of score attempts per player. Min 1, max 1000. Once a player's attempt count exceeds this cap, their leaderboard value no longer updates. If you do not provide a value, there is no attempt cap.

## Response `201`

Tournament created successfully. The tournament is returned in the `future` state.

- object
  - `success` boolean
  - `data` object
    - `tournament` Tournament
      - `tournament_id` string — Unique identifier for the tournament, generated by Gamezop.
      - `game` TournamentGame — Details of the game on which the tournament runs.
        - `code` string — Stable game identifier. This is the same `code` value returned by the [All Games API](/publishers/gamezop/types-of-integration/all-games-api).
        - `name` string — Localized game name. Falls back to English if the requested language is not available.
        - `url` string, uri — Playable URL for the game, with `?lang=<lang>` appended and the `tournament_id` query parameter already included. When sending users to the tournament, you must append a `puid` query parameter identifying each user, for the game to record scores against the tournament correctly. See [how a tournament works](/publishers/gamezop/advanced/tournaments#how-a-tournament-works).
      - `title` string — Tournament title, as provided by you at creation.
      - `status` 'future' | 'live' | 'past' — Current state of the tournament.
      - `starts_at` string, date-time — Tournament start time (UTC, ISO 8601).
      - `ends_at` string, date-time — Tournament end time (UTC, ISO 8601). Computed as `starts_at` + `duration_seconds`.
      - `duration_seconds` integer — Tournament duration in seconds.
      - `created_at` string, date-time — Time at which the tournament was created (UTC, ISO 8601).

## Other responses

- `400` — Bad Request.
- `401` — Unauthorized.
- `403` — Forbidden.
- `429` — Too Many Requests. Standard platform rate limits apply to this endpoint.

---

[API](https://skmtc.net/gamezop/apis/astrozop-apis.md) · [All operations](https://skmtc.net/gamezop/apis/astrozop-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gamezop/astrozop-apis/revisions/485db86a5145/schema)