Skip to content
RallyHere Docs
GitHub

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:update:any, session:*, 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
required

Type of the host

string
Allowed values: dedicated player
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

Unique ID for the host/session relationship

string
>= 1 characters <= 128 characters
host_type
required

Type of the host

string
Allowed values: dedicated player
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 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

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