Matchmaking

Matchmaking

Matchmaking pairs a player with compatible others from a queue. The player submits a ticket that describes the match they want, and ggscale groups them with players whose tickets fit. All calls need the API key and the session token.

Submitting a ticket

POST /v1/matchmaker/tickets creates a ticket. Common fields are mode, game_mode, region, and the group size (min_count and max_count). A player holds at most one active ticket per project. A second create returns 409 with title ticket_already_active and the active_ticket_id to cancel.

GET /v1/matchmaker/tickets/{id} reads a ticket, and DELETE cancels it.

Result modes

The mode you request decides what a match hands back:

• match_only returns the matched roster and a host. You run your own signaling from there.
• game_session returns a joinable game session (session_id, join_code) plus the roster and host. This is the recommended P2P path.
• fleet_allocation provisions a dedicated server for the match. This mode is beta and needs a fleet-scoped key and the dedicated_servers entitlement.

For the peer-to-peer modes, the longest-waiting player becomes the host, carried as host_player_id, and each member's opaque attributes ride along in the roster so peers can connect.

Getting the result

A match arrives as a matchmaker_matched event over the WebSocket. If a client misses it, polling GET /v1/matchmaker/tickets/{id} returns the same result once matched. A dropped connection does not lose the match. See Realtime WebSocket Events.

Example

curl -s -X POST http://localhost:8080/v1/matchmaker/tickets \
  -H "Authorization: Bearer <api_key>" \
  -H "X-Session-Token: <access_token>" \
  -H "Content-Type: application/json" \
  -d '{"mode":"game_session","game_mode":"ranked-2v2","region":"eu-west","min_count":4,"max_count":4}'

Common errors

• 409 ticket_already_active: cancel the returned active_ticket_id first, or reuse that ticket.

Full reference: the /v1/matchmaker/* operations. See also P2P Connectivity and TURN Relay.