4. Start with the API

Once your image has been pushed to Docker Hub and pulled onto nodes (via the webhook you configured in step 1), you can start a session through the API.

Application setup required

Before you can start sessions via the API, an application must be created on the Gameye platform with your image name, networking mode, and resource settings. This is typically done through the Admin Panel. Contact your Gameye administrator if you’re unsure whether your application has been configured.

For full API documentation, see the API V2 overview and the OpenAPI specification.

---

Make your first API call

Send a POST request to create a session:

curl -X POST https://api.production-gameye.gameye.net/session \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "f7965a22-e327-4541-a30e-8262890d3a29",
    "location": "europe",
    "image": "my-very-special-game",
    "env": {
      "my-secret": "my_secret_value"
    },
    "args": ["--max-players=8"],
    "labels": {
      "my-example-tag": "1",
      "another-example-tag": "3"
    },
    "restart": false,
    "ttl": 3600
  }'

Successful response

A successful call returns the host IP and port mappings for the new container:

{
  "host": "203.0.113.42",
  "ports": [
    {
      "type": "udp",
      "container": 7777,
      "host": 49152
    },
    {
      "type": "udp",
      "container": 1024,
      "host": 49153
    }
  ]
}

Your game clients can connect using the IP from host and a port from ports[n].host — for example, 203.0.113.42:49152.

---

How do you know it’s working?

When the API returns a host and ports array, the container is starting (or already running). Use the returned IP and port to connect a game client.

What to check	How
Session created	The POST /session call returns 200 with a host and ports array.
Players can connect	Use the host IP and the ports[n].host port value to connect a game client.
Session cleanup	Call DELETE /session/{id} when the match ends, or let the ttl (time-to-live, in seconds) expire automatically.

Tip

You can list active sessions with GET /session and inspect a specific session with GET /session/{id}. See the API Reference for details.

---

Troubleshooting

Problem	What to check
401 Unauthorized	Verify your API token is correct and included in the Authorization header.
No session returned	Make sure your image name matches the application configured on the platform and that at least one tag is loaded and ready.
Container starts but players can’t connect	Check that the correct ports are exposed (bridge) or that your entrypoint reads the GAMEYE_PORT_* variables (host). See Networking mode affects the Dockerfile.

If you’re still stuck, contact the support team on Discord or email [email protected].

---

Next step

Now that you can create sessions programmatically, explore the full API V2 documentation to learn about session management, log streaming, artifacts, and more.