Create a queue

curl --request POST \
  --url https://api.simpl.gg/v1/queues \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "queue_id": "ranked_2v2",
  "name": "Ranked 2v2",
  "enabled": true,
  "timeout": 120,
  "host_leave_behavior": "promote",
  "max_players": 2,
  "lobby_ttl": 3600,
  "invite_code_config": {
    "enabled": true,
    "length": 6,
    "charset": "alphanumeric",
    "prefix": "SIMPL-"
  },
  "server_settings": {
    "version_tag": "1.2.3",
    "region": "iad",
    "tier": "1x-2g",
    "startup_args": "-log",
    "network_ports": [
      {
        "name": "game_udp",
        "protocol": "udp",
        "internal_port": 7777
      }
    ]
  },
  "matchmaking": {
    "teams": 2,
    "players_per_team": 2,
    "min_players_per_team": 2,
    "timeout": 120,
    "max_party_size": 2,
    "rules": [
      {
        "type": "difference",
        "field": "mmr",
        "max_difference": 200
      },
      {
        "type": "equals",
        "field": "game_version"
      },
      {
        "type": "region",
        "min_overlap": 1
      }
    ]
  }
}
'

{
  "queue_id": "ranked_2v2",
  "name": "Ranked 2v2",
  "enabled": true,
  "max_players": 4,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "timeout": 120,
  "heartbeat": false,
  "heartbeat_timeout": 30,
  "host_leave_behavior": "promote",
  "lobby_ttl": 3600,
  "invite_code_config": {
    "enabled": true,
    "length": 6,
    "charset": "numeric",
    "prefix": "SIMPL-"
  },
  "server_settings": {
    "version_tag": "1.2.3",
    "region": "iad",
    "tier": "1x-2g",
    "network_ports": [
      {
        "name": "game_udp",
        "protocol": "udp",
        "internal_port": 7777,
        "external_port": 30412,
        "host": "37.16.24.10",
        "tls_enabled": false
      }
    ],
    "startup_args": "-log",
    "ttl": 1,
    "auto_restart": false,
    "custom_data": {
      "map": "forest",
      "mode": "ctf"
    }
  },
  "matchmaking": {
    "teams": 2,
    "players_per_team": 2,
    "min_players_per_team": 1,
    "min_teams": 2,
    "team_composition": {
      "monsters": {
        "boss": 1
      },
      "hunters": {
        "medic": 1,
        "assault": 2
      }
    },
    "use_version_from_state": false,
    "timeout": 120,
    "max_party_size": 4,
    "rules": [
      {
        "type": "difference",
        "field": "mmr",
        "max_difference": 200
      }
    ]
  }
}

POST

queues

curl --request POST \
  --url https://api.simpl.gg/v1/queues \
  --header 'Content-Type: application/json' \
  --header 'api-key: <api-key>' \
  --data '
{
  "queue_id": "ranked_2v2",
  "name": "Ranked 2v2",
  "enabled": true,
  "timeout": 120,
  "host_leave_behavior": "promote",
  "max_players": 2,
  "lobby_ttl": 3600,
  "invite_code_config": {
    "enabled": true,
    "length": 6,
    "charset": "alphanumeric",
    "prefix": "SIMPL-"
  },
  "server_settings": {
    "version_tag": "1.2.3",
    "region": "iad",
    "tier": "1x-2g",
    "startup_args": "-log",
    "network_ports": [
      {
        "name": "game_udp",
        "protocol": "udp",
        "internal_port": 7777
      }
    ]
  },
  "matchmaking": {
    "teams": 2,
    "players_per_team": 2,
    "min_players_per_team": 2,
    "timeout": 120,
    "max_party_size": 2,
    "rules": [
      {
        "type": "difference",
        "field": "mmr",
        "max_difference": 200
      },
      {
        "type": "equals",
        "field": "game_version"
      },
      {
        "type": "region",
        "min_overlap": 1
      }
    ]
  }
}
'

{
  "queue_id": "ranked_2v2",
  "name": "Ranked 2v2",
  "enabled": true,
  "max_players": 4,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "timeout": 120,
  "heartbeat": false,
  "heartbeat_timeout": 30,
  "host_leave_behavior": "promote",
  "lobby_ttl": 3600,
  "invite_code_config": {
    "enabled": true,
    "length": 6,
    "charset": "numeric",
    "prefix": "SIMPL-"
  },
  "server_settings": {
    "version_tag": "1.2.3",
    "region": "iad",
    "tier": "1x-2g",
    "network_ports": [
      {
        "name": "game_udp",
        "protocol": "udp",
        "internal_port": 7777,
        "external_port": 30412,
        "host": "37.16.24.10",
        "tls_enabled": false
      }
    ],
    "startup_args": "-log",
    "ttl": 1,
    "auto_restart": false,
    "custom_data": {
      "map": "forest",
      "mode": "ctf"
    }
  },
  "matchmaking": {
    "teams": 2,
    "players_per_team": 2,
    "min_players_per_team": 1,
    "min_teams": 2,
    "team_composition": {
      "monsters": {
        "boss": 1
      },
      "hunters": {
        "medic": 1,
        "assault": 2
      }
    },
    "use_version_from_state": false,
    "timeout": 120,
    "max_party_size": 4,
    "rules": [
      {
        "type": "difference",
        "field": "mmr",
        "max_difference": 200
      }
    ]
  }
}

Authorizations

api-key

string

header

required

Per-project server key, prefixed sk_live_. Full access to every endpoint. Keep it on your backend: never ship it in a game binary.

Body

application/json

queue_id

string

required

Developer-chosen identifier. Unique within the project.

Pattern: ^[a-z0-9_]{1,64}$

Example:

"ranked_2v2"

name

string

required

Example:

"Ranked 2v2"

max_players

integer

required

Required range: 1 <= x <= 100

enabled

boolean

default:true

timeout

integer

Required range: x >= 1

heartbeat

boolean

default:false

heartbeat_timeout

integer

Required range: x >= 1

host_leave_behavior

enum<string>

default:promote

Available options:

promote,

delete

lobby_ttl

integer

Required range: x >= 1

invite_code_config

object

Controls invite code generation for lobbies in this queue. length counts the random portion only. The prefix is not included.

config	output
`length: 6, charset: alphanumeric`	`K7Q2F1`
`length: 6, charset: alphanumeric, prefix: "SIMPL-"`	`SIMPL-K7Q2F1`
`length: 4, charset: numeric, prefix: "GAME-"`	`GAME-4829`
`length: 8, charset: alphabetic`	`KQZRFWPM`

Show child attributes

server_settings

object

Template used to create the game server when a match is made.

Show child attributes

matchmaking

object

How lobbies in this queue are matched against each other. Use either the symmetric fields (teams, players_per_team) or team_composition, not both.

Show child attributes

Response

Queue created.

A matchmaking queue. Queues are first-class resources in Simpl with their own endpoints, not settings buried inside a project config blob.

queue_id

string

required

Example:

"ranked_2v2"

name

string

required

Example:

"Ranked 2v2"

enabled

boolean

required

Disabled queues reject new lobbies with QUEUE_DISABLED.

max_players

integer

required

Maximum players per lobby in this queue.

Required range: 1 <= x <= 100

Example:

4

created_at

string<date-time>

required

updated_at

string<date-time>

required

timeout

integer

Seconds a lobby may sit in this queue before being returned to waiting.

Required range: x >= 1

Example:

120

heartbeat

boolean

default:false

Whether players must heartbeat to stay in the lobby.

heartbeat_timeout

integer

Seconds without a heartbeat before a player is dropped.

Required range: x >= 1

Example:

30

host_leave_behavior

enum<string>

default:promote

What happens when the host leaves. promote transfers host to the longest-present remaining player, delete destroys the lobby.

Available options:

promote,

delete

lobby_ttl

integer

Seconds an idle lobby survives before deletion.

Required range: x >= 1

Example:

3600

invite_code_config

object

Controls invite code generation for lobbies in this queue. length counts the random portion only. The prefix is not included.

config	output
`length: 6, charset: alphanumeric`	`K7Q2F1`
`length: 6, charset: alphanumeric, prefix: "SIMPL-"`	`SIMPL-K7Q2F1`
`length: 4, charset: numeric, prefix: "GAME-"`	`GAME-4829`
`length: 8, charset: alphabetic`	`KQZRFWPM`

Show child attributes

server_settings

object

Template used to create the game server when a match is made.

Show child attributes

matchmaking

object

How lobbies in this queue are matched against each other. Use either the symmetric fields (teams, players_per_team) or team_composition, not both.

Show child attributes

API Reference

Auth

Account

Projects

Keys

Billing

Servers

Builds

Queues

Lobbies

Events

Create a queue

Authorizations

Body

Response