4. Start with the API

In production, your backend or matchmaker starts every session through the Gameye API. This page takes you from an API token to a running session and back.

You need an application with at least one tag loaded on nodes. Create it in the Admin Panel or with the create application endpoint.

For every endpoint and field, see the API V2 overview and the OpenAPI specification.

---

1. Get an API token

Create a token in the Admin Panel under Users → API tokens, or with the create token endpoint. Give it the scopes this guide uses:

Scope	Used for
regions:read	Finding the regions where your image can run
session:start	Starting sessions
session:read	Listing and inspecting sessions
session:stop	Stopping sessions

Send it as a bearer token. The examples below assume it is in $GAMEYE_TOKEN:

export GAMEYE_TOKEN="<your API token>"

2. Find where your image can run

A session’s location is a region name, such as eu-west-1. Ask which regions can run your application right now, using its application name:

curl https://api.production-gameye.gameye.net/available-location/my-game \
  -H "Authorization: Bearer $GAMEYE_TOKEN"

The response lists each region’s id and the IP addresses clients can ping to measure latency. See Get locations.

3. Start a session

curl -X POST https://api.production-gameye.gameye.net/session \
  -H "Authorization: Bearer $GAMEYE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "f7965a22-e327-4541-a30e-8262890d3a29",
    "image": "my-game",
    "location": "eu-west-1",
    "ttl": "1h",
    "args": ["--max-players=8"],
    "env": { "MATCH_MODE": "ranked" },
    "labels": { "match": "1234" }
  }'

Only image (your application name) and location are required:

Field	Meaning
id	Your identifier for the session. Use a UUID. If you leave it out, Gameye generates one.
version	The image tag to run. If you leave it out, Gameye runs the newest loaded tag.
ttl	How long the session may live before Gameye stops it, in minutes or hours ("30m", "2h").
args, env, labels	Command-line arguments, environment variables and labels for this session.
restart	Restart the container automatically if it crashes.

A successful call returns 201 Created with the address players connect to:

{
  "id": "f7965a22-e327-4541-a30e-8262890d3a29",
  "host": "203.0.113.42",
  "ports": [
    { "type": "udp", "container": 7777, "host": 49152 }
  ]
}

Players connect to host on the matching ports[].host port, here 203.0.113.42:49152. Inside the container, the same port is available as GAMEYE_PORT_UDP_7777.

4. Check and stop sessions

List your running sessions with GET /session, or inspect one with GET /session/{id}. See Get sessions.

Stop a session when its match ends:

curl -X DELETE https://api.production-gameye.gameye.net/session/f7965a22-e327-4541-a30e-8262890d3a29 \
  -H "Authorization: Bearer $GAMEYE_TOKEN"

A successful stop returns 204 No Content. A session you don’t stop keeps running until its ttl expires, so always set a ttl as a safety net.

---

Troubleshooting

Response or symptom	What to check
401 Unauthorized	The token is missing, mistyped, or not sent as Authorization: Bearer <token>.
402 Payment Required	Your organization has used up its quota. Contact Gameye support.
403 Forbidden	The token lacks the scope this endpoint needs, such as session:start.
404 Not Found	The application name in image doesn’t exist, or the version tag isn’t loaded in that region yet. Check with tag availability.
Session starts but players can’t connect	In bridge mode, check that the application’s port bindings match the ports your server listens on. In host mode, check that the server listens on the GAMEYE_PORT_* ports. See Choose your network mode.

Still stuck? Ask on Discord or through the support portal.

---

Next step

Explore the API V2 documentation for player tracking, logs, artifacts and more, or set up warm pools so sessions start instantly.