---
title: "POST /session"
method: POST
path: "/session"
---

# POST /session

`POST /session`

## Request

- Base URL: `https://api.sandbox-gameye.gameye.net`
- URL: `https://api.sandbox-gameye.gameye.net/session`
- Auth: HTTP bearer

Allocate a new game session in a specific region. Each session is to be identified by a unique identifier that is provided by the caller. It is  recommended to use a UUID.
In case a warm pool is configured for the specified region and image, an already spun up session will be taken from the pool instead and the given set of program arguments, environment variables and additional labels in the HTTP request will be ignored. Sessions managed by a warm pool will always use the same static set of program arguments and environment variables. The warm pool will then as soon as possible try to replenish itself. If the warm pool is exhausted, a cold allocation will occur as normal.

## Request body

- SessionRunBody
  - `id` string: The unique identifier of the session. If undefined, Gameye will generate a UUIDV4 for you and return it in the API response.
  - `location` string, required: The region the game session is to be hosted in.
  - `image` string, required: The name of the application.
  - `env` object: The list of environment variables to feed the underlying container on startup. This field is ignored when a container is claimed from a warm pool.
  - `args` string[]: The list of program console arguments to feed to the application hosted inside the underlying container. This field is ignored when a container is claimed from a warm pool.
  - `restart` boolean: Indicates whether this session must be automatically restarted on failure. The underlying container will not be restarted in case of a manual termination. This field is ignored when a container is claimed from a warm pool.
  - `labels` object: A collection of user-defined key/value metadata. This field is ignored in case a container is claimed from a warm pool.
  - `version` string: Tag of the image that the session will be run. This tag needs to be available or a 404 will be thrown. If not specified run the tag with the highest priority. This field is ignored when a container is claimed from a warm pool.
  - `ttl` string: The amount of time a container should live for until it is to be automatically (and forcefully) terminated. Valid time units are 'm' and 'h'. Any value than a minute will be rounded up to a minute.
  - `external_id` string: An optional customer-provided identifier for this session.

## Response `201`

A session is running on a machine in the provided region.

- SessionRunOkBody
  - `id` string: The generated unique session ID.
  - `host` string, required: The IP address of the machine that the session is running on.
  - `ports` Port[], required: The list of mapped ports for this session.
    - `type` 'tcp' | 'udp', required: The type of protocol of this port entry.
    - `container` integer, required: The port of the container that is hosted on the machine.
    - `host` integer, required: The host port for mapping the container port.

## Other responses

- `401`: You are not authorized to run a session. Please make sure that the included bearer token is correct.
- `402`: You have exhausted your quota.
- `403`: Your API token may not have the required permissions to invoke this endpoint.
- `404`: The request contains a region or application that does not exist.
- `409`: Cannot start a session with the provided id. Please use a unique identifier for your session. It is recommended to use a UUID.
- `420`: This session can currently not be started in the provided region. This could also be the result of starting too many sessions in a short period of time. Please try again later!
- `422`: Bad request. This may imply that the given request has invalid syntax.

---

[API](https://skmtc.dev/gameye/apis/gameye-session-api-2.md) · [All operations](https://skmtc.dev/gameye/apis/gameye-session-api-2/llms.txt) · [OpenAPI document](https://skmtc.dev/gameye/apis/gameye-session-api-2/revisions/0a019bf29067?raw)