Session Management

session management is at the core of the gameye session api these endpoints allow you to create new game sessions, list active sessions, and stop sessions when they're no longer needed creating a session to start a new game session, you'll need to make a post request to the /session endpoint endpoint post /session request body the request requires a json body with the following fields field type required description location string yes the region where you want to host the session (e g , "eu west 1", "eu central 1") image string yes the name of the game image to run in the container id string no a unique identifier for the session if omitted, the system will generate an rfc4122 compliant uuid env object no environment variables to pass to the container args array no command line arguments to pass to the game server restart boolean no whether to automatically restart the session on failure labels object no custom metadata key value pairs for the session version string no tag of the image to run (defaults to highest priority tag) example request { "location" "eu central 1", "image" "my game server", "env" { "max players" "16", "map rotation" "de dust2,de inferno,de nuke" }, "args" \[ " tickrate=128", " competitive=true" ], "labels" { "game mode" "competitive", "tournament id" "spring cup 2023" }, "restart" false } success response on success, you'll receive a 201 created response with details about the new session { "id" "c5c7c507 f5de 443e b772 af4b444cfc21", "host" "203 0 113 42", "ports" \[ { "type" "tcp", "container" 80, "host" 25159 }, { "type" "tcp", "container" 80, "host" 25160 } ] } note host ports are now allocated from the dedicated range of 20000 30000 to prevent conflicts with the linux kernel's ephemeral port range, improving server startup reliability error responses status code description 401 unauthorized invalid bearer token 404 not found requested location, image, or organization doesn't exist 409 conflict session id already exists 420 enhance your calm location temporarily unavailable or too many requests 422 unprocessable entity invalid request syntax error response example { "statuscode" 404, "code" "resource not found", "message" "unable to start session ", "details" "please make sure the correct image is specified ", "identifier" "3bc545b7 4750 47e6 a918 c93debc58663", "path" "/session", "timestamp" "2023 04 01t12 00 00z" } 🔍 tip always include the identifier when contacting support about errors this helps us quickly trace the exact issue in our systems listing sessions to get a list of your active sessions, use the get request to the /session endpoint endpoint get /session query parameters parameter type required description all boolean no whether to return all sessions regardless of status (default false, only returns running sessions) filter object no filter sessions to include only those matching specific criteria (e g , ?filter\[tag]=v1 2 3 ) filternot object no filter sessions to exclude those matching specific criteria (e g , ?filternot\[status]=exited ) filtering examples include filter ( filter ) get /session?filter\[location]=eu central 1\&filter\[tag]=latest returns sessions matching all specified criteria exclude filter ( filternot ) get /session?filternot\[status]=exited\&filternot\[tag]=beta excludes sessions that match the specified criteria historical sessions ( all ) get /session?all=true include non running sessions (like exited ones) in the results you can combine these filters for precise querying get /session?all=true\&filter\[location]=eu central 1\&filternot\[status]=dead this would return all sessions (including exited ones) in eu central 1, excluding dead sessions example response { "sessions" \[ { "id" "c595bc6f 8522 4a62 95cd 8742136643ea", "image" "my game server", "tag" "v1 2 3", "location" "eu central 1", "host" "203 0 113 42", "created" 1648472895000, "port" { "80/tcp" 25160 }, "status" "running", "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\\"}" } } ] } stopping a session when a game session is over, you can stop it using the delete request endpoint delete /session/{id} path parameters parameter type required description id string yes the unique id of the session you want to stop success response on success, you'll receive a 204 no content response, indicating the session was successfully terminated error responses status code description 401 unauthorized invalid bearer token 404 not found session doesn't exist 409 conflict session already terminated session lifecycle a typical session lifecycle looks like this creation you create a session with post /session running the session runs until you stop it or it crashes termination you stop the session with delete /session/{id} cleanup you can download artifacts if needed session status values when listing sessions, the status field will be one of status description created session container is created but not started running session is running normally restarting session is restarting after a failure exited session has exited (gracefully or by error) dead session container is dead/unresponsive draining host is preparing to shut down, session will be migrated shuttingdown session is gracefully shutting down server unreachable cannot reach the server running this session best practices let the system generate session ids when possible use labels to organize and filter your sessions always stop sessions when they're no longer needed to free up resources check session status before performing operations on them use the combined filtering capabilities to efficiently manage many sessions