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

# Create Tournament API

`POST /v2/tournaments`

## Request

- Base URL: `https://api.astrozop.com`
- URL: `https://api.astrozop.com/v2/tournaments`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/gamezop/apis/astrozop-apis/docs/v2/tournaments/post.ts> (a function with typed inputs; its response is checked against the schema)

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.dev/gamezop/apis/astrozop-apis.md) - [All operations](https://skmtc.dev/gamezop/apis/astrozop-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/gamezop/apis/astrozop-apis/revisions/485db86a5145?raw)