Launch a session

Start a new game session in a specific region. Each session needs a unique ID, which you’ll need to create yourself.

Caution

Each call to the API to launch a session must be a UUID to avoid any issues.

{
  "tab": "examples",
  "url": "https://api.gameye.io/session",
  "name": "Launch a session",
  "method": "POST",
  "request": {
    "pathParameters": [],
    "queryParameters": [],
    "headerParameters": [],
    "bodyDataParameters": [
      {
        "kind": "required",
        "name": "id",
        "type": "string",
        "description": "The unique ID for the session. (use a UUID.)"
      },
      {
        "kind": "required",
        "name": "location",
        "type": "string",
        "children": [],
        "description": "The location or region that you'd prefer to host the game session in. (Check our regions and locations page.)"
      },
      {
        "kind": "required",
        "name": "image",
        "type": "string",
        "children": [],
        "description": "The name of the image for your game, hosted inside a container. "
      },
      {
        "kind": "required",
        "name": "env",
        "type": "Object",
        "children": [
          {
            "name": "Parameter name",
            "kind": "optional",
            "type": "string",
            "description": ""
          }
        ],
        "description": "The list of environment variables you want to feed the container when it starts. [can be left blank]",
        "schema": [
          {
            "name": "Parameter name",
            "kind": "optional",
            "type": "string",
            "description": ""
          }
        ]
      },
      {
        "kind": "required",
        "name": "args",
        "type": "String",
        "children": [],
        "description": "The list of program console arguments to feed to the application that's hosted inside the container. [can be left blank]"
      },
      {
        "kind": "required",
        "name": "restart",
        "type": "Boolean",
        "children": [],
        "description": "Tells us whether we must automatically restart this session if it fails to launch. (We won't restart if you manually shut it down.) "
      },
      {
        "kind": "optional",
        "name": "labels",
        "type": "Object",
        "children": [],
        "description": "Add your own metadata about the session that we'll store inside the configuration."
      },
      {
        "kind": "optional",
        "name": "version",
        "type": "string",
        "children": [],
        "description": "Tag of the image that the session will run. This tag needs to be available\nor it'll throw a 404. If you don't specify a priority, we'll run it with the highest priority."
      },
      {
        "kind": "optional",
        "name": "enableMetrics",
        "type": "string",
        "children": [],
        "description": "Use this to collect details like CPU, memory and network information. Useful for debugging."
      }
    ],
    "formDataParameters": []
  },
  "results": {
    "languages": [
      {
        "id": "Lk2gsKb_VicqqFYOxO77V",
        "code": "// A session has successfully been started on a machine in the provided location.\n \n{\n  \"host\": \"\",\n  \"ports\": [\n    {\n      \"type\": \"\",\n      \"container\": 0,\n      \"host\": 0\n    }\n  ]\n}",
        "language": "200",
        "customLabel": ""
      },
      {
        "id": "bU8t44V4Xs1q_4nl7zw_i",
        "code": "// You are not authorized to start a session. Please make sure that the included bearer\ntoken is correct.",
        "language": "401",
        "customLabel": ""
      },
      {
        "id": "9svqRC683Amkfzz3HsDh-",
        "code": "// The request contains a location, image or organization that does not exist.\n \n",
        "language": "404",
        "customLabel": ""
      },
      {
        "id": "WvXBHe4MZFVNN-HdquNQS",
        "code": "// Cannot start a session with the provided id. Please use a unique identifier\nfor your session. It is recommended to use a UUID.",
        "language": "409",
        "customLabel": ""
      },
      {
        "id": "vKi6RM-av_vuQHEWMupm8",
        "code": "// Bad request. This may imply that the given request has invalid syntax.",
        "language": "422",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "vKi6RM-av_vuQHEWMupm8"
  },
  "examples": {
    "languages": [
      {
        "id": "qT_wn0JzgmVwM_8gWnf08",
        "code": "curl --location --request POST 'https://api.gameye.io/session' \\\n--header 'Accept: application/json' \\\n--data-raw '{\n  \"id\": \"f7965a22-e327-4541-a30e-8262890d3a29\",\n  \"location\": \"europe\",\n  \"image\": \"my-very-special-game\",\n  \"version\": \"buildversion\",\n  \"env\": {\n    \"my-secret\": \"<my_secret_value\"\n  },\n  \"args\": [\n    \"--max-players=8\"\n  ],\n  \"labels\": {\n    \"my-example-tag\": \"1\",\n    \"another-example-tag\": \"3\"\n  },\n  \"restart\": false\n}'",
        "language": "curl",
        "customLabel": ""
      },
      {
        "id": "A7ZR7_leKvaccd1pTOqhw",
        "code": "var myHeaders = new Headers();\nmyHeaders.append(\"Accept\", \"application/json\");\n\nvar raw = \"{\\n  \\\"id\\\": \\\"f7965a22-e327-4541-a30e-8262890d3a29\\\",\\n  \\\"location\\\": \\\"europe\\\",\\n  \\\"image\\\": \\\"nginx\\\",\\n  \\\"env\\\": {},\\n  \\\"args\\\": [\\n    \\\"\\\"\\n  ],\\n  \\\"restart\\\": false,\\n  \\\"labels\\\": {}\\n}\";\n\nvar requestOptions = {\n   method: 'POST',\n   headers: myHeaders,\n   body: raw,\n   redirect: 'follow'\n};\n\nfetch(\"https://api.gameye.io/session\", requestOptions)\n   .then(response => response.text())\n   .then(result => console.log(result))\n   .catch(error => console.log('error', error));",
        "language": "javascript",
        "customLabel": ""
      },
      {
        "id": "JlpdBQhhPIa7wy095CItI",
        "code": "import requests\n\nurl = \"https://api.gameye.io/session\"\n\npayload = \"{\\n  \\\"id\\\": \\\"f7965a22-e327-4541-a30e-8262890d3a29\\\",\\n  \\\"location\\\": \\\"europe\\\",\\n  \\\"image\\\": \\\"nginx\\\",\\n  \\\"env\\\": {},\\n  \\\"args\\\": [\\n    \\\"\\\"\\n  ],\\n  \\\"restart\\\": false,\\n  \\\"labels\\\": {}\\n}\"\nheaders = {\n   'Accept': 'application/json'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)",
        "language": "python",
        "customLabel": ""
      },
      {
        "id": "ikJG1yfEI5Aikwd5XBhts",
        "code": "require \"uri\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.gameye.io/session\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"Accept\"] = \"application/json\"\nrequest.body = \"{\\n  \\\"id\\\": \\\"f7965a22-e327-4541-a30e-8262890d3a29\\\",\\n  \\\"location\\\": \\\"europe\\\",\\n  \\\"image\\\": \\\"nginx\\\",\\n  \\\"env\\\": {},\\n  \\\"args\\\": [\\n    \\\"\\\"\\n  ],\\n  \\\"restart\\\": false,\\n  \\\"labels\\\": {}\\n}\"\n\nresponse = https.request(request)\nputs response.read_body",
        "language": "ruby",
        "customLabel": ""
      },
      {
        "id": "vrD0GRwaANudzyjawE2bB",
        "code": "var request = require('request');\nvar options = {\n   'method': 'POST',\n   'url': 'https://api.gameye.io/session',\n   'headers': {\n      'Accept': 'application/json'\n   },\n   body: '{\"id\":\"string\",\"location\":\"string\",\"image\":\"string\",\"env\":\"Object\",\"args\":\"String\",\"restart\":\"Boolean\",\"labels\":\"Object\"}'\n\n};\nrequest(options, function (error, response) {\n   if (error) throw new Error(error);\n   console.log(response.body);\n});\n",
        "language": "nodejs",
        "customLabel": ""
      }
    ],
    "selectedLanguageId": "qT_wn0JzgmVwM_8gWnf08"
  },
  "description": "",
  "currentNewParameter": {
    "label": "Body Parameter",
    "value": "bodyDataParameters"
  }
}

Note

although not depicted in the API responses, 420 is still returned for sessions that failed to start.