curl --request PATCH \
--url https://api.simpl.gg/v1/servers/{instance_id} \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '
{
"ttl": 7200,
"custom_data": {
"map": "desert"
}
}
'import requests
url = "https://api.simpl.gg/v1/servers/{instance_id}"
payload = {
"ttl": 7200,
"custom_data": { "map": "desert" }
}
headers = {
"api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({ttl: 7200, custom_data: {map: 'desert'}})
};
fetch('https://api.simpl.gg/v1/servers/{instance_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.simpl.gg/v1/servers/{instance_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'ttl' => 7200,
'custom_data' => [
'map' => 'desert'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.simpl.gg/v1/servers/{instance_id}"
payload := strings.NewReader("{\n \"ttl\": 7200,\n \"custom_data\": {\n \"map\": \"desert\"\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.simpl.gg/v1/servers/{instance_id}")
.header("api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"ttl\": 7200,\n \"custom_data\": {\n \"map\": \"desert\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.simpl.gg/v1/servers/{instance_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"ttl\": 7200,\n \"custom_data\": {\n \"map\": \"desert\"\n }\n}"
response = http.request(request)
puts response.read_body{
"instance_id": "abc123",
"name": "ranked-2v2-iad-01",
"status": "launching",
"region": "iad",
"tier": "2x-2g",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"network_ports": [
{
"name": "game",
"protocol": "udp",
"internal_port": 7777,
"external_port": 30412,
"host": "37.16.24.10",
"tls_enabled": false
}
],
"startup_args": [
"-port={{PORT}}"
],
"custom_data": {
"map": "forest",
"mode": "ctf"
},
"ttl": 3600,
"match_id": "xyz789",
"version_tag": "1.2.3",
"version": 12,
"started_at": "2023-11-07T05:31:56Z",
"stopped_at": "2023-11-07T05:31:56Z"
}Update a server
Partial update. startup_args is stored, but a running server keeps the
arguments it was started with. Everything else applies immediately.
curl --request PATCH \
--url https://api.simpl.gg/v1/servers/{instance_id} \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '
{
"ttl": 7200,
"custom_data": {
"map": "desert"
}
}
'import requests
url = "https://api.simpl.gg/v1/servers/{instance_id}"
payload = {
"ttl": 7200,
"custom_data": { "map": "desert" }
}
headers = {
"api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({ttl: 7200, custom_data: {map: 'desert'}})
};
fetch('https://api.simpl.gg/v1/servers/{instance_id}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.simpl.gg/v1/servers/{instance_id}",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "PATCH",
CURLOPT_POSTFIELDS => json_encode([
'ttl' => 7200,
'custom_data' => [
'map' => 'desert'
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"api-key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.simpl.gg/v1/servers/{instance_id}"
payload := strings.NewReader("{\n \"ttl\": 7200,\n \"custom_data\": {\n \"map\": \"desert\"\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.patch("https://api.simpl.gg/v1/servers/{instance_id}")
.header("api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"ttl\": 7200,\n \"custom_data\": {\n \"map\": \"desert\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.simpl.gg/v1/servers/{instance_id}")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"ttl\": 7200,\n \"custom_data\": {\n \"map\": \"desert\"\n }\n}"
response = http.request(request)
puts response.read_body{
"instance_id": "abc123",
"name": "ranked-2v2-iad-01",
"status": "launching",
"region": "iad",
"tier": "2x-2g",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"network_ports": [
{
"name": "game",
"protocol": "udp",
"internal_port": 7777,
"external_port": 30412,
"host": "37.16.24.10",
"tls_enabled": false
}
],
"startup_args": [
"-port={{PORT}}"
],
"custom_data": {
"map": "forest",
"mode": "ctf"
},
"ttl": 3600,
"match_id": "xyz789",
"version_tag": "1.2.3",
"version": 12,
"started_at": "2023-11-07T05:31:56Z",
"stopped_at": "2023-11-07T05:31:56Z"
}Authorizations
Per-project server key, prefixed sk_live_. Full access to every
endpoint. Keep it on your backend: never ship it in a game binary.
Path Parameters
Server instance identifier.
"abc123"
Body
Partial update. Only the supplied fields change.
Free-form developer-defined data. Carried verbatim and surfaced to the game
server in /simpl/its_simpl.json. Soft cap of 64KB serialized; exceeding it
returns CUSTOM_DATA_TOO_LARGE (error_id 2008).
{ "map": "forest", "mode": "ctf" }
x >= 0Stored for the server's next machine. A running machine keeps the
arguments it was started with. null clears them.
641024["-port={{PORT}}"]
Response
The updated server.
"abc123"
"ranked-2v2-iad-01"
launching, running, stopped Datacenter region a server runs in. 15 regions are supported.
| code | location |
|---|---|
ams | Amsterdam, Netherlands |
arn | Stockholm, Sweden |
cdg | Paris, France |
dfw | Dallas, Texas (US) |
ewr | Secaucus, NJ (US) |
fra | Frankfurt, Germany |
iad | Ashburn, Virginia (US) |
lax | Los Angeles, California (US) |
lhr | London, United Kingdom |
nrt | Tokyo, Japan |
ord | Chicago, Illinois (US) |
sin | Singapore, Singapore |
sjc | San Jose, California (US) |
syd | Sydney, Australia |
yyz | Toronto, Canada |
Every region is available to every project. Capacity is Simpl's problem, not yours: pick the region closest to your players.
ams, arn, cdg, dfw, ewr, fra, iad, lax, lhr, nrt, ord, sin, sjc, syd, yyz "iad"
Machine tier, named transparently as <cpu>-<memory>. 1x = one shared
vCPU, 2p = two performance (dedicated) vCPUs, 2g = 2 GB of memory.
No guessing what small or nano means.
1x-512, 1x-1g, 1x-2g, 2x-2g, 4x-4g, 1p-2g, 1p-4g, 2p-4g, 2p-8g "2x-2g"
Show child attributes
Show child attributes
Extra command-line arguments for this server, one string per argument. A
single string is refused with 400 "startup_args is an array of strings":
it cannot say where one argument ends.
- ZIP build: appended after the build's executable and
launch_args. - docker_image build: appended to the image's own
ENTRYPOINTandCMD, after the build'slaunch_args, asdocker run <image> <args>would.
For both, the Simpl entrypoint substitutes {{PORT}}, {{PORT_<NAME>}},
{{UDP_BIND}}, {{TCP_BIND}} and {{SERVER_ID}} in each one. A Docker
image build registered before Docker images were wrapped (base_version
null) has no Simpl entrypoint, so nothing is substituted in it.
641024["-port={{PORT}}"]
Free-form developer-defined data. Carried verbatim and surfaced to the game
server in /simpl/its_simpl.json. Soft cap of 64KB serialized; exceeding it
returns CUSTOM_DATA_TOO_LARGE (error_id 2008).
{ "map": "forest", "mode": "ctf" }
Seconds before Simpl stops this server automatically. 0 or omitted
means no TTL.
x >= 03600
Match this server was created for, if any.
"xyz789"
Build name requested at creation time.
"1.2.3"
Resolved integer build version actually running.
12