Create Instance Request

POST

/session/v1/session/{session_id}/instance

Request an instance be spawned for the session, or register self as a host of the instance

Required Permissions:

• For any player (including themselves) any of: session:*, session:update:any, session:update:self

Required Session Permissions: SessionPermissions.session_admin if user does not have the session:update:any auth permission

Authorizations

• HTTPBearerHeadersOrCookie

Parameters

Path Parameters

session_id

required

string

>= 1 characters <= 128 characters

Request Body ^required

A request body to create an instance resource in a session

object

instance_id

Unique ID for the instance, a new one will be generated if not provided

string

>= 1 characters <= 128 characters

instance_startup_params

Parameters used by the host to startup. For UE5 this will contain the map and gamemode

object

map

required

Name of the map for the instance to spawn with

string

mode

Game mode for the instance to spawn in

string

misc_params

required

Additional commandline parameters for the instance

string

custom_data

Custom data to pass through to the instance

object

key

additional properties

string

>= 1 characters <= 4096 characters

host_type

Type of the host

string

Allowed values: dedicated player preallocated

instance_request_template_id

Which instance request template should be used to request this instance. Takes priority over instance_startup_params and host_type

string format: uuid

host_player_uuid

Player UUID of the host, if the host type is player

string format: uuid

custom_data

Instance-defined custom data

object

key

additional properties

string

>= 1 characters <= 4096 characters

Responses

200

Successful Response

Information about the instance resource in a session

object

allocation_id

Allocation ID for instance that’s been spun up

string

>= 1 characters <= 128 characters

instance_id

required

Unique ID for the host/session relationship

string

>= 1 characters <= 128 characters

host_type

required

Type of the host

string

Allowed values: dedicated player preallocated

host_player_id

Player ID of the host, if the host type is player

integer

host_player_uuid

Player UUID of the host, if the host type is player

string format: uuid

host_dedicated_process_id

Unique ID for the process that is running this instance

string

host_dedicated_server_id

Unique ID for the machine running the instance

string

join_status

required

Is the instance joinable at this time?

string

Allowed values: requested allocated pending joinable unjoinable closed

join_params

Parameters to join the instance

object

public_conn_str

required

Public connection string for instance

string

private_conn_str

required

Private connection string for instance

string

custom_data

Custom data to join a instance

object

key

additional properties

string

>= 1 characters <= 4096 characters

instance_startup_params

Parameters used by the host to startup. For UE5 this will contain the map and gamemode

object

map

required

Name of the map for the instance to spawn with

string

mode

Game mode for the instance to spawn in

string

misc_params

required

Additional commandline parameters for the instance

string

custom_data

Custom data to pass through to the instance

object

key

additional properties

string

>= 1 characters <= 4096 characters

version

Product Client Version number. Used for compatibility checking with players

string format: semver

21.3.15-beta+12345

created

required

Datetime that enforces that a timezone is given. Unix timestamps are allowed and forced into the UTC time zone

string format: date-time

custom_data

Instance-defined custom data

object

key

additional properties

string

>= 1 characters <= 4096 characters

instance_health

The current status of the instance

string

Allowed values: healthy unhealthy degraded unknown

match_making_profile_id

The profile id that this instance was spawned from

string

>= 1 characters <= 128 characters

match_id

The match ID associated with this instance

string

403

Forbidden

object

auth_success

boolean

default: true

error_code

required

string

desc

required

string

422

Validation Error

object

detail

Array<object>

object

loc

required

Array

msg

required

string

type

required

string