Custom Matchmaker Integration

import { Aside } from ‘@astrojs/starlight/components’;

Gameye’s Session API is matchmaker-agnostic. Any backend that can make an HTTP request can allocate a dedicated game server session. No SDK is required — you call POST /session with your image name and target location, and Gameye returns a host IP and port in under 0.5 seconds.

This guide covers the full lifecycle: region selection, session creation, delivering connection details to players, join/leave tracking, and shutdown.

Prerequisites

A Gameye sandbox account — provisioned within 24 hours
An API token (provided with your account)
A Docker image of your game server pushed to Docker Hub
Your application configured in the Admin Panel — image name, ports, networking mode, regions
Your matchmaker backend capable of making HTTP POST/PUT/DELETE requests

API URLs:

Sandbox: api.sandbox-gameye.gameye.net
Production: api.gameye.io

Integration flow

Clients ping available regions — matchmaker collects latency data
Match found — matchmaker selects lowest-latency region
Matchmaker calls POST /session — Gameye starts the server
Gameye returns the server IP and port (~0.5s)
Matchmaker delivers connection details to matched players
Players connect — matchmaker calls PUT /session/player/join
Match ends — game server or matchmaker calls DELETE /session/{id}

Authentication

All API calls require a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

See Authentication for details.

Step 1: Select a region

Call GET /available-location/{image} to get a list of regions with a pingable IP per region. Have game clients ping those IPs and report latency to your matchmaker.

curl https://api.gameye.io/available-location/your-image \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Step 2: Create a session

Call POST /session with your image, location, and optional match configuration:

curl -X POST https://api.gameye.io/session \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "your-image",
    "location": "eu-west-1",
    "env": {
      "MAP": "dust2",
      "GAME_MODE": "ranked",
      "MATCH_ID": "abc-123"
    },
    "ttl": 3600
  }'

Response (201 Created):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "host": "185.12.34.56",
  "ports": [
    { "type": "udp", "container": 7777, "host": 27015 }
  ]
}

Key fields

Field	Required	Notes
`image`	Yes	Your application name in Gameye
`location`	Yes	Region from `/available-location`
`env`	No	Key-value env vars injected at container start
`ttl`	No	Auto-terminate after this many seconds
`id`	No	UUID4 — auto-generated if omitted
`version`	No	Docker image tag
`args`	No	Command-line arguments for the server process

Step 3: Deliver connection details

Return host and ports[0].host to your matched players via whatever channel your matchmaker uses — WebSocket push, polling, or lobby state update.

Step 4: Track players (optional)

Call PUT /session/player/join when players connect and DELETE /session/player/leave when they disconnect. This enables:

Live player counts via GET /session
Backfill queries (find sessions with open slots)

# Join
curl -X PUT https://api.gameye.io/session/player/join \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "session": "550e8400-...", "players": ["player_a", "player_b"] }'

# Leave
curl -X DELETE https://api.gameye.io/session/player/leave \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "players": ["player_a"] }'

Step 5: Stop the session

Sessions terminate via:

DELETE /session/{id} from your matchmaker or game server
TTL expiry (set at creation time)

Gameye sends SIGTERM to the container, giving your server a chance to flush state before shutdown.

curl -X DELETE https://api.gameye.io/session/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Error codes

Code	Meaning
401	Unauthorized — token missing or invalid
404	Image or location not found
409	Duplicate session ID
420	Capacity limit — retry after ~60 seconds
422	Invalid request body

See Error Codes for full details.