curl --request POST \
--url https://api.simpl.gg/v1/servers \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '
{
"name": "ranked-2v2-iad-01",
"region": "iad",
"tier": "1x-2g",
"version_tag": "1.2.3",
"startup_args": "-log",
"ttl": 3600,
"network_ports": [
{
"name": "game_udp",
"protocol": "udp",
"internal_port": 7777
}
],
"custom_data": {
"map": "forest",
"mode": "ctf"
}
}
'import requests
url = "https://api.simpl.gg/v1/servers"
payload = {
"name": "ranked-2v2-iad-01",
"region": "iad",
"tier": "1x-2g",
"version_tag": "1.2.3",
"startup_args": "-log",
"ttl": 3600,
"network_ports": [
{
"name": "game_udp",
"protocol": "udp",
"internal_port": 7777
}
],
"custom_data": {
"map": "forest",
"mode": "ctf"
}
}
headers = {
"api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'ranked-2v2-iad-01',
region: 'iad',
tier: '1x-2g',
version_tag: '1.2.3',
startup_args: '-log',
ttl: 3600,
network_ports: [{name: 'game_udp', protocol: 'udp', internal_port: 7777}],
custom_data: {map: 'forest', mode: 'ctf'}
})
};
fetch('https://api.simpl.gg/v1/servers', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'ranked-2v2-iad-01',
'region' => 'iad',
'tier' => '1x-2g',
'version_tag' => '1.2.3',
'startup_args' => '-log',
'ttl' => 3600,
'network_ports' => [
[
'name' => 'game_udp',
'protocol' => 'udp',
'internal_port' => 7777
]
],
'custom_data' => [
'map' => 'forest',
'mode' => 'ctf'
]
]),
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"
payload := strings.NewReader("{\n \"name\": \"ranked-2v2-iad-01\",\n \"region\": \"iad\",\n \"tier\": \"1x-2g\",\n \"version_tag\": \"1.2.3\",\n \"startup_args\": \"-log\",\n \"ttl\": 3600,\n \"network_ports\": [\n {\n \"name\": \"game_udp\",\n \"protocol\": \"udp\",\n \"internal_port\": 7777\n }\n ],\n \"custom_data\": {\n \"map\": \"forest\",\n \"mode\": \"ctf\"\n }\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.simpl.gg/v1/servers")
.header("api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"ranked-2v2-iad-01\",\n \"region\": \"iad\",\n \"tier\": \"1x-2g\",\n \"version_tag\": \"1.2.3\",\n \"startup_args\": \"-log\",\n \"ttl\": 3600,\n \"network_ports\": [\n {\n \"name\": \"game_udp\",\n \"protocol\": \"udp\",\n \"internal_port\": 7777\n }\n ],\n \"custom_data\": {\n \"map\": \"forest\",\n \"mode\": \"ctf\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.simpl.gg/v1/servers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"ranked-2v2-iad-01\",\n \"region\": \"iad\",\n \"tier\": \"1x-2g\",\n \"version_tag\": \"1.2.3\",\n \"startup_args\": \"-log\",\n \"ttl\": 3600,\n \"network_ports\": [\n {\n \"name\": \"game_udp\",\n \"protocol\": \"udp\",\n \"internal_port\": 7777\n }\n ],\n \"custom_data\": {\n \"map\": \"forest\",\n \"mode\": \"ctf\"\n }\n}"
response = http.request(request)
puts response.read_body{
"instance_id": "abc123",
"name": "ranked-2v2-iad-01",
"status": "launching",
"region": "iad",
"tier": "1x-2g",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"network_ports": [
{
"name": "game_udp",
"protocol": "udp",
"internal_port": 7777,
"external_port": 30412,
"host": "37.16.24.10",
"tls_enabled": false
}
],
"startup_args": "-log",
"custom_data": {
"map": "forest",
"mode": "ctf"
},
"ttl": 3600,
"match_id": "xyz789",
"auto_restart": false,
"version_tag": "1.2.3",
"version": 12,
"started_at": "2023-11-07T05:31:56Z",
"stopped_at": "2023-11-07T05:31:56Z"
}Create a server
Launches a machine running the build identified by version_tag. The
server boots with /simpl/its_simpl.json already written. See
docs/its_simpl.md.
curl --request POST \
--url https://api.simpl.gg/v1/servers \
--header 'Content-Type: application/json' \
--header 'api-key: <api-key>' \
--data '
{
"name": "ranked-2v2-iad-01",
"region": "iad",
"tier": "1x-2g",
"version_tag": "1.2.3",
"startup_args": "-log",
"ttl": 3600,
"network_ports": [
{
"name": "game_udp",
"protocol": "udp",
"internal_port": 7777
}
],
"custom_data": {
"map": "forest",
"mode": "ctf"
}
}
'import requests
url = "https://api.simpl.gg/v1/servers"
payload = {
"name": "ranked-2v2-iad-01",
"region": "iad",
"tier": "1x-2g",
"version_tag": "1.2.3",
"startup_args": "-log",
"ttl": 3600,
"network_ports": [
{
"name": "game_udp",
"protocol": "udp",
"internal_port": 7777
}
],
"custom_data": {
"map": "forest",
"mode": "ctf"
}
}
headers = {
"api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'ranked-2v2-iad-01',
region: 'iad',
tier: '1x-2g',
version_tag: '1.2.3',
startup_args: '-log',
ttl: 3600,
network_ports: [{name: 'game_udp', protocol: 'udp', internal_port: 7777}],
custom_data: {map: 'forest', mode: 'ctf'}
})
};
fetch('https://api.simpl.gg/v1/servers', 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",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'ranked-2v2-iad-01',
'region' => 'iad',
'tier' => '1x-2g',
'version_tag' => '1.2.3',
'startup_args' => '-log',
'ttl' => 3600,
'network_ports' => [
[
'name' => 'game_udp',
'protocol' => 'udp',
'internal_port' => 7777
]
],
'custom_data' => [
'map' => 'forest',
'mode' => 'ctf'
]
]),
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"
payload := strings.NewReader("{\n \"name\": \"ranked-2v2-iad-01\",\n \"region\": \"iad\",\n \"tier\": \"1x-2g\",\n \"version_tag\": \"1.2.3\",\n \"startup_args\": \"-log\",\n \"ttl\": 3600,\n \"network_ports\": [\n {\n \"name\": \"game_udp\",\n \"protocol\": \"udp\",\n \"internal_port\": 7777\n }\n ],\n \"custom_data\": {\n \"map\": \"forest\",\n \"mode\": \"ctf\"\n }\n}")
req, _ := http.NewRequest("POST", 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.post("https://api.simpl.gg/v1/servers")
.header("api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"ranked-2v2-iad-01\",\n \"region\": \"iad\",\n \"tier\": \"1x-2g\",\n \"version_tag\": \"1.2.3\",\n \"startup_args\": \"-log\",\n \"ttl\": 3600,\n \"network_ports\": [\n {\n \"name\": \"game_udp\",\n \"protocol\": \"udp\",\n \"internal_port\": 7777\n }\n ],\n \"custom_data\": {\n \"map\": \"forest\",\n \"mode\": \"ctf\"\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.simpl.gg/v1/servers")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"ranked-2v2-iad-01\",\n \"region\": \"iad\",\n \"tier\": \"1x-2g\",\n \"version_tag\": \"1.2.3\",\n \"startup_args\": \"-log\",\n \"ttl\": 3600,\n \"network_ports\": [\n {\n \"name\": \"game_udp\",\n \"protocol\": \"udp\",\n \"internal_port\": 7777\n }\n ],\n \"custom_data\": {\n \"map\": \"forest\",\n \"mode\": \"ctf\"\n }\n}"
response = http.request(request)
puts response.read_body{
"instance_id": "abc123",
"name": "ranked-2v2-iad-01",
"status": "launching",
"region": "iad",
"tier": "1x-2g",
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z",
"network_ports": [
{
"name": "game_udp",
"protocol": "udp",
"internal_port": 7777,
"external_port": 30412,
"host": "37.16.24.10",
"tls_enabled": false
}
],
"startup_args": "-log",
"custom_data": {
"map": "forest",
"mode": "ctf"
},
"ttl": 3600,
"match_id": "xyz789",
"auto_restart": false,
"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.
Query Parameters
Which project to act on. Required when authenticating with a developer
session (bearer_auth), which names no project of its own; ignored when
authenticating with an API key, which carries its project already.
A project belonging to another account returns PROJECT_NOT_FOUND (7001)
rather than a 403, so this cannot be used to probe for project ids.
"proj_abc123"
Body
"ranked-2v2-iad-01"
Datacenter region a server runs in. 16 regions are supported.
| code | location |
|---|---|
ams | Amsterdam, Netherlands |
arn | Stockholm, Sweden |
bom | Mumbai, India |
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, bom, 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-256, 1x-512, 1x-1g, 1x-2g, 2x-2g, 2x-4g, 4x-4g, 4x-8g, 1p-2g, 1p-4g, 1p-8g, 2p-16g "1x-2g"
Build name to run.
"1.2.3"
Pin an exact build version. Omit to run the latest build carrying
version_tag.
12
Ports the game process binds. External mappings are assigned by Simpl.
Show child attributes
Show child attributes
"-log"
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 >= 0Response
Server created and launching.
"abc123"
"ranked-2v2-iad-01"
launching, running, stopped Datacenter region a server runs in. 16 regions are supported.
| code | location |
|---|---|
ams | Amsterdam, Netherlands |
arn | Stockholm, Sweden |
bom | Mumbai, India |
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, bom, 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-256, 1x-512, 1x-1g, 1x-2g, 2x-2g, 2x-4g, 4x-4g, 4x-8g, 1p-2g, 1p-4g, 1p-8g, 2p-16g "1x-2g"
Show child attributes
Show child attributes
Arguments appended to the executable's command line.
"-log"
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"
Restart the machine automatically if the process exits.
Build name requested at creation time.
"1.2.3"
Resolved integer build version actually running.
12