Skip to content

Update Instance Info

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

Update info about the instance. If the instance was a result of the instance allocation system, then it will have an allocation id. Allocated instances must send their allocation id for updates to ensure they are still the proper allocation.

Required Permissions:

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

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

Authorizations

Parameters

Path Parameters

session_id
required
string
>= 1 characters <= 128 characters

Request Body required

A request body to update the instance resource in a session

object
allocation_id

Allocation ID for instance that’s been spun up

string
>= 1 characters <= 128 characters
join_status

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
version

Product Client Version number. Used for compatibility checking with players. Must be compatible with all players to spawn

string format: semver
21.3.15-beta+12345
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
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

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