> ## Documentation Index
> Fetch the complete documentation index at: https://docs.platform.gamezop.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Tournament API
> 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.
Tournaments module is only available with paid plans. [Contact us](https://business.gamezop.com/contact-us/enquire-now) to know more.
## About this API
Use this API to create a new tournament on any of your eligible games. Before you start, make sure you have gone through the [Tournaments overview](/publishers/gamezop/advanced/tournaments) for concepts, conventions, and rate limits that apply across all Tournaments APIs.
`starts_at` must be in the future and within the next 15 days. `ends_at` is computed automatically as `starts_at` + `duration_seconds`.
***
## API specification
## OpenAPI
````yaml /openapi-gzp.json post /v2/tournaments
openapi: 3.1.0
info:
title: Gamezop APIs
version: 1.0.0
description: >-
OpenAPI specification for Gamezop endpoints including game catalog,
leaderboard metadata, and other integration APIs.
servers:
- url: https://api.gamezop.com
description: Gamezop API
security:
- bearerAuth: []
paths:
/v2/tournaments:
post:
summary: Create Tournament API
description: >-
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.
operationId: createTournament
parameters:
- name: Idempotency-Key
in: header
required: true
description: >-
Unique string per request. Sending the same key again returns the
original response instead of creating a duplicate tournament. Keys
are retained for 10 minutes, scoped per token.
schema:
type: string
example: c1a9a1de-42a1-4e5b-9f6d-8a2f3b7c1d20
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentCreateRequest'
examples:
sample:
summary: Example request
value:
game_code: B1MfIa4QCg
title: Friday 1 Hour Challenge
starts_at: '2026-06-01T10:00:00Z'
duration_seconds: 3600
max_score_attempts: 3
responses:
'201':
description: >-
Tournament created successfully. The tournament is returned in the
`future` state.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
data:
type: object
properties:
tournament:
$ref: '#/components/schemas/Tournament'
examples:
sample:
summary: Example response
value:
success: true
data:
tournament:
tournament_id: tour_01HZZ2S9GQK6Y3V2S8D7A9F2BC
game:
code: B1MfIa4QCg
name: Bubble Shooter
url: >-
https://www.gamezop.com/g/B1MfIa4QCg?lang=en&tournament_id=tour_01HZZ2S9GQK6Y3V2S8D7A9F2BC
title: Friday 1 Hour Challenge
status: future
starts_at: '2026-06-01T10:00:00Z'
ends_at: '2026-06-01T11:00:00Z'
duration_seconds: 3600
created_at: '2026-05-26T12:30:00Z'
'400':
description: Bad Request.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
INVALID_REQUEST:
summary: Malformed request body
value:
code: INVALID_REQUEST
message: Malformed request body.
success: false
INVALID_DURATION:
summary: duration_seconds is outside the 300 to 259200 range
value:
code: INVALID_DURATION
message: duration_seconds is outside the 300 to 259200 range.
success: false
MISSING_IDEMPOTENCY_KEY:
summary: Idempotency-Key header not provided
value:
code: MISSING_IDEMPOTENCY_KEY
message: Idempotency-Key header not provided.
success: false
'401':
description: Unauthorized.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
UNAUTHORIZED:
summary: Invalid or missing token
value:
code: UNAUTHORIZED
message: Invalid or missing token.
success: false
'403':
description: Forbidden.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
GAME_NOT_ALLOWED:
summary: Token does not have access to the requested game_code
value:
code: GAME_NOT_ALLOWED
message: >-
Your token does not have access to the requested
game_code.
success: false
'429':
description: >-
Too Many Requests. Standard platform rate limits apply to this
endpoint.
content:
application/json:
schema:
$ref: '#/components/schemas/TournamentErrorResponse'
examples:
RATE_LIMIT_EXCEEDED:
summary: Too many requests
value:
code: RATE_LIMIT_EXCEEDED
message: >-
Too many requests. Standard platform rate limits apply to
this endpoint.
success: false
components:
schemas:
TournamentCreateRequest:
type: object
required:
- game_code
- title
- starts_at
- duration_seconds
properties:
game_code:
type: string
description: >-
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.
example: B1MfIa4QCg
title:
type: string
minLength: 3
maxLength: 100
description: Tournament title. 3 to 100 characters.
example: Friday 1 Hour Challenge
starts_at:
type: string
format: date-time
description: >-
Tournament start time (UTC, ISO 8601). Must be in the future, and no
more than 15 days from now.
example: '2026-06-01T10:00:00Z'
duration_seconds:
type: integer
minimum: 300
maximum: 259200
description: >-
Tournament duration in seconds. Minimum 300 (5 minutes), maximum
259200 (3 days). `ends_at` is computed as `starts_at` +
`duration_seconds`.
example: 3600
max_score_attempts:
type: integer
minimum: 1
maximum: 1000
description: >-
(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.
example: 3
Tournament:
type: object
properties:
tournament_id:
type: string
description: Unique identifier for the tournament, generated by Gamezop.
game:
$ref: '#/components/schemas/TournamentGame'
title:
type: string
description: Tournament title, as provided by you at creation.
status:
type: string
enum:
- future
- live
- past
description: Current state of the tournament.
starts_at:
type: string
format: date-time
description: Tournament start time (UTC, ISO 8601).
ends_at:
type: string
format: date-time
description: >-
Tournament end time (UTC, ISO 8601). Computed as `starts_at` +
`duration_seconds`.
duration_seconds:
type: integer
description: Tournament duration in seconds.
created_at:
type: string
format: date-time
description: Time at which the tournament was created (UTC, ISO 8601).
TournamentErrorResponse:
type: object
properties:
code:
type: string
description: Machine-readable error code identifying the failure.
message:
type: string
description: Human-readable description of the error.
success:
type: boolean
description: Boolean value that is always `false` in error responses.
TournamentGame:
type: object
description: Details of the game on which the tournament runs.
properties:
code:
type: string
description: >-
Stable game identifier. This is the same `code` value returned by
the [All Games
API](/publishers/gamezop/types-of-integration/all-games-api).
name:
type: string
description: >-
Localized game name. Falls back to English if the requested language
is not available.
url:
type: string
format: uri
description: >-
Playable URL for the game, with `?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).
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: UUID
description: >-
You can find the Bearer token for this API under Settings & Admin > API
Tokens within the [Gamezop Business
Dashboard](https://dashboard.gamezop.com).
````