Gameye Session API
The Session API from Gameye — 4 operation(s) for session.
OpenAPI Specification
openapi: 3.0.0
info:
title: Gameye Artifacts Session API
version: 1.2.1
description: 'The Gameye Session API offers an agnostic way of hosting containerized game sessions without having to worry about geographic capacity or scalability issues. The API offers a complete suite of features to host a server based multiplayer game.
# Authentication
All endpoints of the Gameye Session API require authorization. This is done through Bearer Token Authentication. A bearer token is thus required in the HTTP header of each request.
For example: ```Authorization: Bearer <token>```
'
x-logo:
url: https://static.gameye.com/images/android-chrome-512x512.png
altText: Gameye Logo
servers:
- url: https://api.sandbox-gameye.gameye.net
description: The main sandbox environment.
- url: https://api.production-gameye.gameye.net
description: The main production environment.
tags:
- name: Session
paths:
/session:
post:
operationId: session-run
description: '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.
'
security:
- api-token:
- session:start
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SessionRun'
responses:
201:
description: 'A session is running on a machine in the provided region.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SessionRunOk'
401:
description: 'You are not authorized to run a session. Please make sure that the included bearer token is correct.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
402:
description: 'You have exhausted your quota.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
403:
description: 'Your API token may not have the required permissions to invoke this endpoint.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
404:
description: 'The request contains a region or application that does not exist.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
409:
description: 'Cannot start a session with the provided id. Please use a unique identifier for your session. It is recommended to use a UUID.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
420:
description: '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!
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
422:
description: 'Bad request. This may imply that the given request has invalid syntax.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Session
get:
operationId: session-list
parameters:
- name: all
in: query
required: false
schema:
type: boolean
description: "Whether to return all sessions regardless of status in the response. \nThe default value for this is 'false', which would only return running sessions.\n"
- name: location
in: query
required: false
schema:
type: string
description: 'Filter results by location.
'
- name: image
in: query
required: false
schema:
type: string
description: 'Filter results by image.
'
- name: tag
in: query
required: false
schema:
type: string
description: 'Filter results by tag.
'
- name: host
in: query
required: false
schema:
type: string
description: 'Filter results by host IP address.
'
- name: playerCount
in: query
required: false
style: deepObject
schema:
type: object
description: 'Filter results by player count. The following keys are available: - ''lt'': Less than - ''gt'': Greater than
Combined with the ''location'' filter above, this would for example allow users to search for specific sessions within a specific region and with less than X amount of players which is good to have for backfill purposes.
'
additionalProperties:
type: integer
- name: filter
in: query
required: false
style: deepObject
schema:
type: object
description: 'A list or record of tags to filter a list of sessions on. If none of the sessions meet the provided filter criteria, naturally an empty list of sessions is returned.
'
additionalProperties:
type: string
summary: Lists a collection of active sessions.
description: 'Lists all of the active sessions that are tied to your API token. Note that it only returns sessions that are active. Those that have already been stopped, will not be included.
'
security:
- api-token:
- session:read
responses:
200:
description: 'Successfully looked up all of the active sessions that are tied to your API token.
'
content:
application/json:
schema:
$ref: '#/components/schemas/SessionListOk'
401:
description: 'You are not authorized to fetch a list of active sessions. Please make sure that the included bearer token is correct.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
403:
description: 'Your API token may not have the required permissions to invoke this endpoint.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Session
/session/{id}:
get:
operationId: describe-session
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The id of the session.
summary: Describes a single session.
description: 'Describe a single session by ID.
'
security:
- api-token:
- session:read
responses:
200:
description: 'Successfully looked up the specified session.
'
content:
application/json:
schema:
$ref: '#/components/schemas/DescribedSession'
401:
description: 'You are not authorized to describe sessions. Please make sure that the included bearer token is correct.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
403:
description: 'Your API token may not have the required permissions to invoke this endpoint.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
404:
description: 'The specified session does not exist. Please provide a correct session id.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Session
delete:
operationId: session-stop
description: 'Stops an active session from running by killing the underlying container. The container is killed by sending in a SIGTERM signal.
'
parameters:
- name: id
in: path
required: true
schema:
type: string
description: The id of the session.
security:
- api-token:
- session:stop
responses:
204:
description: 'The session has successfully been terminated.
'
401:
description: "You are not authorized to stop a session. Please make sure that the \nincluded bearer token is correct.\n"
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
403:
description: 'Your API token may not have the required permissions to invoke this endpoint.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
404:
description: 'The specified session does not exist. Please provide a correct session id.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
409:
description: 'This session has already been terminated.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Session
/session/player/join:
put:
operationId: join-session
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/JoinSession'
responses:
200:
description: 'One or more player IDs have been registered as having joined this session.
'
content:
application/json:
schema:
$ref: '#/components/schemas/JoinSessionOk'
401:
description: 'You are not authorized to start a session. Please make sure that the included bearer token is correct.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
403:
description: 'Your API token may not have the required permissions to invoke this endpoint.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
404:
description: 'The provided session does not exist.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
422:
description: 'Bad request. This may imply that the given request has invalid syntax.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Session
/session/player/leave:
delete:
operationId: leave-session
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LeaveSession'
responses:
200:
description: 'One or more player IDs have been removed from the session.
'
content:
application/json:
schema:
$ref: '#/components/schemas/LeaveSessionOk'
401:
description: 'You are not authorized to use this endpoint. Please make sure that the included bearer token is correct.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
403:
description: 'Your API token may not have the required permissions to invoke this endpoint.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
404:
description: 'The provided session does not exist.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
422:
description: 'Bad request. This may imply that the given request has invalid syntax.
'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
tags:
- Session
components:
schemas:
FieldViolation:
type: object
additionalProperties: false
required:
- field
- description
properties:
field:
type: string
description:
type: string
SessionListEntry:
type: object
required:
- id
- image
- location
- host
- created
- port
properties:
id:
type: string
description: 'The unique identifier of the session.
'
example: f7965a22-e327-4541-a30e-8262890d3a29
x-order: 1
image:
type: string
description: 'The name of the image of the game that is hosted inside the container.
'
example: nginx
x-order: 2
tag:
type: string
description: 'The build tag of the image the container is derived from.
'
example: latest
x-order: 3
location:
type: string
description: 'The location or region that the game session is hosted in.
'
example: europe
x-order: 4
host:
type: string
description: 'The IP address of the host machine the game session is hosted on.
'
example: a.b.c.d
x-order: 5
created:
type: number
description: 'The unix timestamp the session was created in.
'
example: 1648472895000
x-order: 6
port:
type: object
description: 'A record of exposed ports for this container.
'
additionalProperties:
type: number
example:
port:
80/tcp: 49160
x-order: 7
status:
$ref: '#/components/schemas/SessionStatus'
x-order: 8
labels:
type: object
additionalProperties:
type: string
description: 'The collection of user-defined key/value metadata stored inside the configuration of the session.
'
example:
labels:
env: '{"GAMEYE_SESSION_ID":"c595bc6f-8522-4a62-95cd-8742136643ea","GAMEYE_HOST":"a.b.c.d"}'
tags: '{"my-example-tag":"1","another-example-tag":"3"}'
x-order: 9
playerCount:
type: integer
x-order: 10
JoinSessionOk:
type: object
additionalProperties: false
required:
- count
- players
properties:
count:
type: integer
description: 'The total amount of players that are in this session.
'
players:
type: array
description: 'The list of player ID''s to join this session.
'
items:
type: string
Port:
type: object
additionalProperties: false
required:
- type
- container
- host
properties:
type:
type: string
description: 'The type of protocol of this port entry.
'
enum:
- tcp
- udp
container:
type: integer
description: 'The port of the container that is hosted on the machine.
'
minimum: 1
maximum: 65535
host:
type: integer
description: 'The host port for mapping the container port.
'
minimum: 1
maximum: 65535
SessionRunOk:
type: object
additionalProperties: false
required:
- host
- ports
properties:
id:
type: string
description: 'The generated unique session ID.
'
host:
type: string
description: 'The IP address of the machine that the session is running on.
'
ports:
type: array
description: 'The list of mapped ports for this session.
'
items:
$ref: '#/components/schemas/Port'
example:
id: c5c7c507-f5de-443e-b772-af4b444cfc21
host: a.b.c.d
ports:
- type: tcp
container: 80
host: 49159
- type: tcp
container: 80
host: 49159
DescribedSession:
type: object
required:
- id
- image
- tag
- location
- host
- created
- port
- status
- labels
- players
properties:
id:
type: string
description: 'The unique identifier of the session.
'
example: f7965a22-e327-4541-a30e-8262890d3a29
x-order: 1
image:
type: string
description: 'The name of the image of the game that is hosted inside the container.
'
example: nginx
x-order: 2
tag:
type: string
description: 'The build tag of the image the container is derived from.
'
example: latest
x-order: 3
location:
type: string
description: 'The location or region that the game session is hosted in.
'
example: europe
x-order: 4
host:
type: string
description: 'The IP address of the host machine the game session is hosted on.
'
example: a.b.c.d
x-order: 5
created:
type: number
description: 'The unix timestamp the session was created in.
'
example: 1648472895000
x-order: 6
port:
type: object
description: 'A record of exposed ports for this container.
'
additionalProperties:
type: number
example:
port:
80/tcp: 49160
x-order: 7
status:
$ref: '#/components/schemas/SessionStatus'
x-order: 8
labels:
type: object
additionalProperties:
type: string
description: 'The collection of user-defined key/value metadata stored inside the configuration of the session.
'
example:
labels:
env: '{"GAMEYE_SESSION_ID":"c595bc6f-8522-4a62-95cd-8742136643ea","GAMEYE_HOST":"a.b.c.d"}'
tags: '{"my-example-tag":"1","another-example-tag":"3"}'
x-order: 9
players:
$ref: '#/components/schemas/DescribedSessionPlayers'
x-order: 10
LeaveSessionOk:
type: object
additionalProperties: false
required:
- count
- players
properties:
count:
type: integer
description: 'The total amount of players that are in this session.
'
players:
type: array
description: 'The list of player ID''s to leave this session.
'
items:
type: string
DescribedSessionPlayers:
type: object
required:
- joined
- joinedCount
properties:
joined:
type: array
items:
type: string
joinedCount:
type: integer
LeaveSession:
type: object
additionalProperties: false
required:
- players
properties:
players:
type: array
description: 'The list of player ID''s to join this session.
'
items:
type: string
SessionListOk:
type: object
additionalProperties: false
required:
- sessions
properties:
sessions:
type: array
items:
$ref: '#/components/schemas/SessionListEntry'
example:
sessions:
- id: c595bc6f-8522-4a62-95cd-8742136643ea
image: my-very-special-game
location: frankfurt
host: a.b.c.d
created: 1648472895000
port:
80/tcp: 49160
labels:
env: '{"GAMEYE_SESSION_ID":"this-is-my-test-session-103","GAMEYE_HOST":"a.b.c.d"}'
tags: '{"my-example-tag":"1","another-example-tag":"3"}'
ErrorResponse:
type: object
required:
- statusCode
- code
- message
- details
- path
- identifier
- timestamp
properties:
statusCode:
type: integer
code:
type: string
message:
type: string
details:
type: string
path:
type: string
timestamp:
type: string
identifier:
type: string
violations:
type: array
items:
$ref: '#/components/schemas/FieldViolation'
SessionRun:
type: object
additionalProperties: false
required:
- location
- image
properties:
id:
type: string
description: 'The unique identifier of the session. If undefined, Gameye will generate a UUIDV4
for you and return it in the API response.
'
minLength: 1
example: f7965a22-e327-4541-a30e-8262890d3a29
location:
type: string
description: 'The region the game session is to be hosted in.
'
minLength: 1
example: europe
image:
type: string
description: 'The name of the application.
'
minLength: 1
example: nginx
env:
type: object
description: '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.
'
additionalProperties:
type: string
minLength: 1
example:
env:
my-secret: <some_very_secret_value>
args:
type: array
description: '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.
'
items:
type: string
minLength: 1
example:
- --max-players=8
- --match-type=quick-play
restart:
description: '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.
'
type: boolean
example: false
labels:
type: object
additionalProperties:
type: string
description: 'A collection of user-defined key/value metadata. This field is ignored in case a container is claimed from a warm pool.
'
x-go-type-skip-optional-pointer: true
example:
labels:
my-example-tag: '1'
another-example-tag: '3'
version:
type: string
description: '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:
type: string
description: '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.
'
examples:
one_hour:
value: 1h
description: 'The underlying container will be forcefully terminated after an hour.
'
two_and_a_half_hours:
value: 2h30m
description: 'The underlying container will be forcefully terminated after a lifetime of two and a half hours.
'
minute:
value: 1m
description: 'The underlying container will be forcefully terminated after a minute.
'
external_id:
type: string
description: "An optional customer-provided identifier for this session.\n \n"
example:
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
JoinSession:
type: object
additionalProperties: false
required:
- session
- players
properties:
session:
type: string
description: 'The ID of the session.
'
players:
type: array
description: 'The list of player ID''s to join this session.
'
items:
type: string
SessionStatus:
type: string
x-go-type-skip-optional-pointer: true
description: 'The current runtime status of the underlying container.
'
enum:
- created
- running
- restarting
- exited
- dead
- draining
- shuttingdown
- server_unreachable
securitySchemes:
api-token:
type: http
scheme: bearer
bearerFormat: token
externalDocs:
url: https://docs.gameye.com