Source: https://gameye.com/platform-scope/ --- title: "Gameye Platform Scope — API Capabilities & Architecture | Gameye" description: "Complete reference: what Gameye does, how sessions flow from API call to player connection, and every capability available through the Session API." --- Platform Reference # Platform Scope What Gameye is, what it does, and exactly what you can control through the API. Session API How do matchmaker integrations work? Global Infrastructure Container Orchestration Updated October 16, 2026 In one sentence Gameye is a managed container orchestration platform for multiplayer game servers. You call `POST /session` with a region and a Docker image. Gameye starts the container — on bare metal or cloud, whichever has capacity — and returns an IP address and port within 0.5 seconds. Players connect. You pay per second the session is active. That's the entire model. ## How does session lifecycle work? Every session passes through three states. Understanding the transition is the foundation of integrating with Gameye correctly. 1 Started Container allocated. Gameye has placed the session on a node in your requested region. The session ID, host IP, and port mappings are returned in the `POST /session` response. The container is starting up — it is not yet ready for player connections. ↓ 2 Running Container is live and reachable. Your game server process is accepting connections. Players can be directed to the host and ports returned at creation. Billing accumulates per second in this state. ↓ 3 Stopped Container terminated — via `DELETE /session/{id}`, TTL expiry, or your game server process exiting. Billing ends. Stopped sessions are no longer returned by `GET /session`. Artifacts can be retrieved before cleanup if configured. ## What API capabilities are available? All operations are HTTP. Authentication is a Bearer token in every request header. Two environments exist: sandbox (`api.sandbox-gameye.gameye.net`) and production (`api.production-gameye.gameye.net`). The sandbox is identical in API surface — use it for integration testing without production billing. Authentication `Authorization: Bearer YOUR_TOKEN_HERE` All endpoints require this header. A `401` response means the token is missing, malformed, expired, or lacks permissions for the resource. Contact [support@gameye.com](mailto:support@gameye.com) to obtain a token. ### POST /session — Create a session The core operation. Allocates a new game server container in a specified region. Returns connection details within ~0.5 seconds on average. | Field | Type | Required | Description | `location` | string | Yes | Region to host the session (e.g. `europe`, `us-east`). Use `GET /available-location/{image}` to confirm availability before creating.| | `image` | string | Yes | Name of the application (Docker image) registered in your Gameye organisation.| | `id` | string | No | Caller-provided session UUID. If omitted, Gameye generates a UUIDv4. Must be unique — a `409` is returned if the ID already exists.| | `version` | string | No | Image tag. Defaults to the highest-priority tag configured in your application.| | `env` | map | No | Environment variables injected into the container at startup. Use for game mode flags, match config, server settings, or secrets.| | `args` | array | No | Console arguments passed to the container entrypoint. Example: `["--max-players=16", "--map=dust2"]`| | `labels` | map | No | Arbitrary key-value metadata stored with the session. Returned unchanged in `GET /session` calls. Useful for match IDs, game modes, or internal tracking.| | `ttl` | integer | No | Maximum session lifetime in seconds. Container is force-terminated and billing stops when TTL expires. Recommended for development environments to prevent runaway costs.| | `restart` | boolean | No | Auto-restart container on crash. Mutually exclusive with `ttl` in most configurations.| 201 Created Session started. Returns `id`, `host` (IP address), and `ports` array — each port object contains `type` (TCP/UDP), `container` (internal port), and `host` (external port). 409 Conflict Session ID already exists. Use unique UUIDs per session, or omit `id` and let Gameye generate one. 420 Location unavailable or rate-limited. Retry after a short delay. This is transient — capacity is added automatically. 404 Not Found Location, image, or organisation not found. Verify the location name via `GET /available-location` and the image name in the Admin Panel. ### GET /session — List active sessions Returns all sessions currently active under your API token. Stopped sessions are excluded — once terminated, a session will not appear here. | Response field | Type | Description | `id` | string | Session UUID| | `image` | string | Application name| | `tag` | string | Image tag running| | `location` | string | Region the session is hosted in| | `host` | string | IP address players connect to| | `created` | number | Unix timestamp (ms) of session creation| | `port` | map | Port mappings (container port → host port)| | `status` | string | Current state (Started / Running / Stopped)| | `labels` | map | Labels set at creation| | `playerCount` | number | Number of players currently joined| ### GET /session/{id} — Describe a session Returns the same schema as the list endpoint, but for a single session. Use this to poll status after creation, or to retrieve connection details for a known session ID. Returns `404` if the session does not exist or has been stopped. The `players` object in the response contains `joined` (array of player identifiers) and `joinedCount` (integer). These are populated by the player tracking endpoints below. ### DELETE /session/{id} — Terminate a session Sends `SIGTERM` to the container and stops billing. Returns `204 No Content` on success. Returns `409` if the session is already stopped. Your matchmaker or game backend should call this endpoint when a match ends rather than relying solely on TTL. ### POST /session/player/join & /leave — Player tracking Two endpoints for recording which players are in a session. These are optional but enable accurate `playerCount` and `players.joined` data on session queries. Useful for matchmaker backfilling logic — knowing how many slots remain in a running session allows you to add players to an existing match rather than spinning a new one. ### GET /available-location/{image} — Check capacity Returns all locations currently capable of hosting your image, along with IPv4 addresses per location for client-side latency measurement via ICMP ping. Call this before `POST /session` when you want to route sessions to the lowest-latency region that has capacity. **Do not cache this list.** Available locations can change as capacity shifts across providers and regions. Query it fresh per matchmaking cycle when latency routing is required. ### GET /logs — Log streaming Streams stdout/stderr from a running container. Use for real-time debugging during development, or to pipe server logs into your observability stack. Access requires the session ID. ### GET /artifact — Artifact retrieval Downloads files written by the game server process before shutdown — crash dumps, match replays, persistent save data, or any file written to a configured path. Configure artifact paths in the Admin Panel; retrieval is available after the session stops. ### GET /tag — Tag verification Confirms that a specific image tag exists and is available in your organisation before launching a session with it. Use in CI/CD pipelines to gate deployments — verify the tag is present before switching your matchmaker to request it. ## How is the infrastructure architected? Bare metal + cloud burst Gameye maintains dedicated bare metal fleets in each region. Sessions are placed on bare metal by default — predictable, non-oversubscribed performance. When bare metal capacity is reached, the orchestrator automatically bursts onto cloud providers. Your game doesn't know or care which it landed on. Multi-provider redundancy Every region runs across multiple infrastructure providers. If one provider has an issue, sessions are automatically placed on an alternative within the same region. No manual intervention required. This is on by default — there is no configuration needed. Resource profiles Each container receives guaranteed CPU and RAM as defined in your resource profile. Gameye does not oversubscribe resources — what you configure is what your container gets, regardless of other sessions on the same node. Profiles are set per application in the Admin Panel. Port binding modes **Bridge networking:** Gameye auto-assigns an ephemeral external port (32768–60299) and maps it to your container's internal port. No Dockerfile changes needed. **Host networking:** A specific host port is reserved and injected as an environment variable (`GAMEYE_PORT_TCP_8080`, `GAMEYE_PORT_UDP_7777`). Your server binary reads and binds to it. Requires a custom entrypoint. ## What are the core objects? | Object | What it is | **Application** | Your game server's Docker image paired with configuration — resource profile, port bindings, registry credentials, and tag priority. Think of it as the template. Sessions are running instances of an application.| | **Session** | An active container spawned from an application. Has a unique ID, host IP, port mappings, lifecycle state, labels, and player tracking data. Billing is per second a session is active.| | **Region** | A named geographic area (`europe`, `us-east`, `asia-northeast`, etc.) where Gameye maintains infrastructure. Specified at session creation. Gameye load-balances across providers within a region automatically.| | **Location** | A specific data centre or cloud zone within a region. Locations handle the actual load-balancing within a region. Exposed via `GET /available-location` for latency-based routing.| | **Resource Profile** | CPU and memory guarantee per container. Set per application. Not oversubscribed — your container gets exactly what is configured.| | **TTL** | Maximum session lifetime in seconds. Container is force-terminated at expiry and billing stops. Recommended for dev/test environments.| | **Label** | Arbitrary key-value metadata attached at session creation and returned on queries. Stored and returned unchanged — not interpreted by the platform. Use for match IDs, game modes, or any tracking your system needs.| ## How do matchmaker integrations work? Gameye sits downstream of your matchmaker. The matchmaker decides when a match is ready — Gameye receives the `POST /session` call and returns connection details that the matchmaker forwards to players. The full loop from "match found" to "server ready" takes ~0.5 seconds. Native integration Unity Matchmaker A Cloud Code module enables Unity Matchmaker queues to allocate Gameye sessions directly. Your existing queues, pools, and matchmaking rules require no changes — the module handles the `POST /session` call and returns connection details to Unity Matchmaker's player notification flow. Native integration Pragma Engine Ships as an official `ServerProviderPlugin` inside Pragma Engine 2025.2. Configure a Capacity Provider pointing at Gameye — no custom code required. The allocation handoff is handled entirely within Pragma's matchmaking loop. Native integration Nakama A Go package (`github.com/Gameye/nakama-fleetmanager`) provides a Fleet Manager implementation for Nakama 3.21+. Manages the full session lifecycle — creation, player tracking, backfilling, and termination. Five environment variables required: `GAMEYE_API_TOKEN`, `GAMEYE_API_URL`, `GAMEYE_API_IMAGE`, `GAMEYE_API_IMAGE_VERSION`, `GAMEYE_API_REGION`. Native integration — [see integration guide](https://gameye.com/flexmatch-integration/) AWS FlexMatch FlexMatch sends match events via SNS. Gameye connects via an AWS Lambda that calls `POST /session` on a `MatchmakingSucceeded` event and returns connection details through FlexMatch's player notification flow. Supported — contact for details PlayFab / Azure PlayFab Matchmaking can trigger session creation via Gameye's HTTP API. Contact the team for the current integration pattern and any helper tooling. Supported Custom / homebrew Any system that can make an authenticated HTTP `POST` request can integrate with Gameye. The Session API is simple enough to call from a game client, a backend Lambda, a dedicated matchmaker service, or a game server itself signalling for a new match. ## What does the onboarding flow look like? Gameye's trial is self-serve. Onboarding follows five steps. 1 Docker Hub account Your game server image must be accessible to Gameye's pull infrastructure. Gameye pulls from Docker Hub or GitHub Container Registry. Other OCI-compatible registries are available on request. 2 Organisation setup Gameye creates your organisation in the Admin Panel. Users, applications, and billing are all scoped to your organisation. Team members can be added with configurable access levels. 3 Dockerfile & image push Build and push your game server Docker image. No Gameye-specific SDK required in the image. Your existing game server binary runs as-is. Configure your image name and tag in the Admin Panel as an Application. 4 Port configuration Configure which ports your game server listens on and the networking mode (bridge or host). For host networking, your server reads the port from an injected environment variable (`GAMEYE_PORT_UDP_7777`). For bridge, Gameye assigns an ephemeral port automatically. 5 First API call Call `POST /session` with your bearer token, image name, and a region. A successful response returns a host IP and port. Direct a game client to those coordinates and you have a running, connected session. You're in production. ## How does billing work? Per-second active sessions Billing starts when a session enters the Running state and stops the moment it is terminated — via `DELETE /session`, TTL expiry, or process exit. Idle capacity is not charged. There is no standing fleet cost. No egress fees Data transfer is included in the compute rate. Player traffic, log streaming, and artifact downloads are not billed separately. The number on your pricing page is the whole bill. Published rates Gameye publishes pricing publicly at [gameye.com/pricing](https://gameye.com/pricing/). You can model costs in a spreadsheet before speaking to anyone. No sales call required to understand what you'll pay. TTL as cost control Set a `ttl` on sessions in development or test environments to cap the maximum duration of any single session. The container is force-terminated at expiry regardless of state, stopping the billing clock. Go deeper - [Full API documentation →](https://gameye.com/docs/) - [How game server orchestration works — platform overview](https://gameye.com/how-it-works/) - [Matchmaker integrations — Unity Matchmaker, Pragma, Nakama, FlexMatch](https://gameye.com/matchmaker-integrations/) - [Pricing — $0.07/vCPU/hr, no egress fees](https://gameye.com/pricing/) Get started ## Start your free trial today. Request a token, push your image, call `POST /session`. Your first live session in under a day. [Start Building →](https://trial.gameye.com/)