Sessions

Provides session management functions for both streaming and native clients, including World queuing and travel.

Fetch Sessions

Retrieves and returns all world sessions that belong to the given Organization, for administration purposes. Supports filtering the returned Sessions by various criteria.

GEThttps://your-organization-id.m2worlds.io/api/sessions/

Authorization

BearerAuth

Query parameters

Header parameters

Response

200400

Returns an array of sessions for the given organization

Body

application/json

sessionId*string

The ID of the session

projectId*string

The ID of a project

organizationId*string

The ID of an organization

userId*string

The ID of a user

launchContextIdstring

The ID of a launch context

worldIdstring

The ID of a world

streamStatus*any of

The state of the session

enumenumenumenumenumenumenumenumenumenumenum

clientTypeany of

The type of client

enumenum

creationTime*string (date-time)

The time the session was created

startTimestring (date-time)

The time the session started streaming

updateTimestring (date-time)

The time the session was last updated

expiryTimestring (date-time)

The time the session expires

failureReasonstring

deletionReasonstring

parentSessionIdstring

The ID of the parent Session

parentWorldIdstring

The ID of the parent World

childSessionIdstring

The ID of the child Session

childWorldIdstring

The ID of the child World

streamTagsarray of string

streamValuesobject

streamContextIdstring

The ID of the Stream Context being used by this Session

streamIdstring

slotIdstring

The ID of the streaming slot from the Stream Manager

providerConfigany of

Config data for the chosen provider

objectobject

metadataobject

The metadata of a session

deviceTypestring

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text",
      "x-m2-world-id": "text"
    },
});
const data = await response.json();

Response

200400

[
  {
    "sessionId": "text",
    "projectId": "text",
    "organizationId": "text",
    "userId": "text",
    "launchContextId": "text",
    "worldId": "text",
    "streamStatus": "QUEUED",
    "clientType": "Streaming",
    "creationTime": "2024-11-21T06:28:59.658Z",
    "startTime": "2024-11-21T06:28:59.658Z",
    "updateTime": "2024-11-21T06:28:59.658Z",
    "expiryTime": "2024-11-21T06:28:59.658Z",
    "failureReason": "text",
    "deletionReason": "text",
    "parentSessionId": "text",
    "parentWorldId": "text",
    "childSessionId": "text",
    "childWorldId": "text",
    "streamTags": [
      "text"
    ],
    "streamContextId": "text",
    "streamId": "text",
    "slotId": "text",
    "providerConfig": {
      "name": "gdn",
      "cmsId": "text",
      "nonce": "text",
      "redirect": "text",
      "partnerId": "text",
      "zone": "text",
      "state": "text",
      "windowed": false
    },
    "metadata": {
      "browserName": "text",
      "browserVersion": 0,
      "osName": "text",
      "deviceModel": "text",
      "deviceType": "text",
      "ubitusSupported": false,
      "geforceSupported": false,
      "forceProvider": "text",
      "forceCapacity": "text"
    },
    "deviceType": "text"
  }
]

Create Session

Creates a Session for the current user. May return a World-scoped Session if a World ID is supplied and World-scoped Sessions are enabled in the Launch Context - otherwise a Launch Context-scoped Session will be returned.

Any existing Sessions belonging to the user will be invalidated, and they will be disconnected from those Sessions within 30 seconds.

If a World ID is supplied, and there is no capacity available for the requested World, the returned Session will be in the Queued state and the client must poll the Refresh Session endpoint until they reach the head of the queue.

POSThttps://your-organization-id.m2worlds.io/api/sessions/

Authorization

BearerAuth

Header parameters

Body

application/json

worldIdstring

The ID of a world

clientTypeany of

The type of client

enumenum

startTimestring (date-time)

The time the session started streaming

updateTimestring (date-time)

The time the session was last updated

expiryTimestring (date-time)

The time the session expires

failureReasonstring

deletionReasonstring

parentSessionIdstring

The ID of the parent Session

parentWorldIdstring

The ID of the parent World

childSessionIdstring

The ID of the child Session

childWorldIdstring

The ID of the child World

streamTagsarray of string

streamValuesobject

streamContextIdstring

The ID of the Stream Context being used by this Session

streamIdstring

slotIdstring

The ID of the streaming slot from the Stream Manager

providerConfigany of

Config data for the chosen provider

objectobject

metadataobject

The metadata of a session

deviceTypestring

Response

2004XX

Returns the sessionId of the created session

Body

application/json

sessionId*string

The ID of the session

signedSessionIdstring

The signed ID of a session for use with unauthenticated keep alive requests.

providerConfigany of

Config data for the chosen provider

objectobject

state*any of

The state of the session

enumenumenumenumenumenumenumenumenumenumenum

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text",
      "x-m2-launch-context-id": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

2004XX

{
  "sessionId": "text",
  "signedSessionId": "text",
  "providerConfig": {
    "name": "gdn",
    "cmsId": "text",
    "nonce": "text",
    "redirect": "text",
    "partnerId": "text",
    "zone": "text",
    "state": "text",
    "windowed": false
  },
  "state": "QUEUED"
}

Service health check

GEThttps://your-organization-id.m2worlds.io/api/sessions/healthz

Response

200

Provides information about the service status.

Body

application/json

statusMessage (string)

Provides information about the service status.

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/healthz', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

text

Get Session

Fetches and returns the specified Session.

GEThttps://your-organization-id.m2worlds.io/api/sessions/{sessionId}/

Authorization

BearerAuth

Path parameters

sessionId*string

The ID of the session

Header parameters

Response

200404

Stores data for a Session

Body

application/json

sessionId*string

The ID of the session

projectId*string

The ID of a project

organizationId*string

The ID of an organization

userId*string

The ID of a user

launchContextIdstring

The ID of a launch context

worldIdstring

The ID of a world

streamStatus*any of

The state of the session

enumenumenumenumenumenumenumenumenumenumenum

clientTypeany of

The type of client

enumenum

creationTime*string (date-time)

The time the session was created

startTimestring (date-time)

The time the session started streaming

updateTimestring (date-time)

The time the session was last updated

expiryTimestring (date-time)

The time the session expires

failureReasonstring

deletionReasonstring

parentSessionIdstring

The ID of the parent Session

parentWorldIdstring

The ID of the parent World

childSessionIdstring

The ID of the child Session

childWorldIdstring

The ID of the child World

streamTagsarray of string

streamValuesobject

streamContextIdstring

The ID of the Stream Context being used by this Session

streamIdstring

slotIdstring

The ID of the streaming slot from the Stream Manager

providerConfigany of

Config data for the chosen provider

objectobject

metadataobject

The metadata of a session

deviceTypestring

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/{sessionId}/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text",
      "x-m2-launch-context-id": "text"
    },
});
const data = await response.json();

Response

200404

{
  "sessionId": "text",
  "projectId": "text",
  "organizationId": "text",
  "userId": "text",
  "launchContextId": "text",
  "worldId": "text",
  "streamStatus": "QUEUED",
  "clientType": "Streaming",
  "creationTime": "2024-11-21T06:28:59.658Z",
  "startTime": "2024-11-21T06:28:59.658Z",
  "updateTime": "2024-11-21T06:28:59.658Z",
  "expiryTime": "2024-11-21T06:28:59.658Z",
  "failureReason": "text",
  "deletionReason": "text",
  "parentSessionId": "text",
  "parentWorldId": "text",
  "childSessionId": "text",
  "childWorldId": "text",
  "streamTags": [
    "text"
  ],
  "streamContextId": "text",
  "streamId": "text",
  "slotId": "text",
  "providerConfig": {
    "name": "gdn",
    "cmsId": "text",
    "nonce": "text",
    "redirect": "text",
    "partnerId": "text",
    "zone": "text",
    "state": "text",
    "windowed": false
  },
  "metadata": {
    "browserName": "text",
    "browserVersion": 0,
    "osName": "text",
    "deviceModel": "text",
    "deviceType": "text",
    "ubitusSupported": false,
    "geforceSupported": false,
    "forceProvider": "text",
    "forceCapacity": "text"
  },
  "deviceType": "text"
}

Refresh Session

Refreshes the given Session - should be called periodically as long as the Session is required.

For new Sessions in the Queued state, this endpoint should be called periodically (as often as every 5s) by either the frontend UI or the Unreal client until it reaches the Ready or Active state.

Streaming clients will be provided with connection information via the providerConfig field in the response, which can be used to connect to the chosen streaming provider.

Native clients must call the /api/worlds/:worldId/connection endpoint to retrieve deployment info. If the token field is populated, it must be used as the bearer token for the request.

Once connected to the World, this endpoint should then continue to be called periodically (at least once every 30s) by the client to indicate that the Session is still in use and should not be expired or the user disconnected.

The returned Session may transition to the Failure state if an error was encountered during the refresh process. Alternatively, if the Session was deleted or expired, this will be reflected in the returned value and the client should react accordingly.

POSThttps://your-organization-id.m2worlds.io/api/sessions/{sessionId}/

Authorization

BearerAuth

Path parameters

sessionId*string

The ID of the session

Header parameters

Response

200404

Describes the current state of the session.

Body

application/json

sessionId*string

The ID of the session

state*any of

The state of the session

enumenumenumenumenumenumenumenumenumenumenum

providerConfigany of

Config data for the chosen provider

objectobject

tokenstring

Access token to use to retrieve World server information.

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/{sessionId}/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text",
      "x-m2-world-id": "text"
    },
});
const data = await response.json();

Response

200404

{
  "sessionId": "text",
  "state": "QUEUED",
  "providerConfig": {
    "name": "gdn",
    "cmsId": "text",
    "nonce": "text",
    "redirect": "text",
    "partnerId": "text",
    "zone": "text",
    "state": "text",
    "windowed": false
  },
  "token": "text"
}

Delete Session

Soft-deletes the specified Session, disconnecting the user from any active experiences they may be partaking in. Any resources used by the user, such as streaming slots, will be automatically recovered.

If the session was created for world travel, and has not yet reached the Ready state, calling this endpoint will remove the session and return the parent Session to the Active state. Streaming resources will not be recovered, as they are assumed to still be in use.

DELETEhttps://your-organization-id.m2worlds.io/api/sessions/{sessionId}/

Authorization

BearerAuth

Path parameters

sessionId*string

The ID of the session

Header parameters

Response

404

The error object returned by the API when an error occurs

Body

application/json

error*string

HTTP error message

codestring

Fastify error code

message*string

User error message

statusCode*number

HTTP status code

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/{sessionId}/', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text",
      "x-m2-world-id": "text"
    },
});
const data = await response.json();

Response

404

{
  "error": "text",
  "code": "text",
  "message": "text",
  "statusCode": 0
}

Admit Queued Session

Admits a Queued Session, allowing the client to join the respective World.

POSThttps://your-organization-id.m2worlds.io/api/sessions/{sessionId}/admit

Authorization

BearerAuth

Path parameters

sessionId*string

The ID of the session

Header parameters

Response

4XX

The error object returned by the API when an error occurs

Body

application/json

error*string

HTTP error message

codestring

Fastify error code

message*string

User error message

statusCode*number

HTTP status code

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/{sessionId}/admit', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text",
      "x-m2-world-id": "text"
    },
});
const data = await response.json();

Response

4XX

{
  "error": "text",
  "code": "text",
  "message": "text",
  "statusCode": 0
}

Create Session for World Travel

Creates a linked Session into another World, to support World Travel.

This endpoint should be called if the user wishes to perform World Travel from the World of their current Session to another World. A new Session will be created that the client should refresh until they are admitted into the new world.

If the user no longer wishes to World Travel, the client should delete the new Session and resume refreshing their original Session.

Once the new World is ready for connection, the new World will reach the Ready state, and their original World will enter the terminal Transited state and must no longer be used.

POSThttps://your-organization-id.m2worlds.io/api/sessions/{sessionId}/travel

Authorization

BearerAuth

Path parameters

sessionId*string

The ID of the session

Header parameters

Body

application/json

worldId*string

The ID of a world

Response

4XX

The error object returned by the API when an error occurs

Body

application/json

error*string

HTTP error message

codestring

Fastify error code

message*string

User error message

statusCode*number

HTTP status code

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/{sessionId}/travel', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text",
      "x-m2-world-id": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "worldId": "text"
    }),
});
const data = await response.json();

Response

4XX

{
  "error": "text",
  "code": "text",
  "message": "text",
  "statusCode": 0
}

Refresh World Session with signed sesssion ID

Refreshes the session and returns the updated state, using a signed session ID. This is typically provided as the keepAlivePath field in returned Sessions.

This endpoint is intended for use by clients that do not have an access token that may last the entire length of the session.

Such clients must call this endpoint every 30s until the Session is no longer required, at which point clients should call the delete endpoint to clear up the Session's resources.

POSThttps://your-organization-id.m2worlds.io/api/sessions/{signedSessionId}/refresh/

Authorization

BearerAuth

Path parameters

signedSessionId*string

The signed ID of a session for use with unauthenticated keep alive requests.

Header parameters

Response

2004XX

Describes the current state of the session.

Body

application/json

sessionId*string

The ID of the session

state*any of

The state of the session

enumenumenumenumenumenumenumenumenumenumenum

providerConfigany of

Config data for the chosen provider

objectobject

tokenstring

Access token to use to retrieve World server information.

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/{signedSessionId}/refresh/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text"
    },
});
const data = await response.json();

Response

2004XX

{
  "sessionId": "text",
  "state": "QUEUED",
  "providerConfig": {
    "name": "gdn",
    "cmsId": "text",
    "nonce": "text",
    "redirect": "text",
    "partnerId": "text",
    "zone": "text",
    "state": "text",
    "windowed": false
  },
  "token": "text"
}

Delete World Session with signed sesssion ID

Refreshes the session and returns the updated state, using a signed session ID. This is typically provided as the keepAlivePath field in returned Sessions.

This endpoint is intended for use by clients that do not have an access token that may last the entire length of the session.

Such clients should call this endpoint when the Session is no longer required, to more promptly clean up used resources for use by other users.

DELETEhttps://your-organization-id.m2worlds.io/api/sessions/{signedSessionId}/refresh/

Authorization

BearerAuth

Path parameters

signedSessionId*string

The signed ID of a session for use with unauthenticated keep alive requests.

Header parameters

Response

2044XX

Default Response

Body

application/json

any

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/{signedSessionId}/refresh/', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text"
    },
});
const data = await response.json();

Response

4XX

{
  "error": "text",
  "code": "text",
  "message": "text",
  "statusCode": 0
}

Keep Alive Session

For Launch Context-scoped streaming Sessions, indicates the Session is still in use, preventing it from being automatically expired and terminating the user's experience.

POSThttps://your-organization-id.m2worlds.io/api/sessions/{signedSessionId}/keepalive/

Authorization

BearerAuth

Path parameters

signedSessionId*string

The signed ID of a session for use with unauthenticated keep alive requests.

Header parameters

Response

2004XX

Returns the new expiry time of the session

Body

application/json

expiry*string (date-time)

The time the session expires

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/{signedSessionId}/keepalive/', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text",
      "x-m2-launch-context-id": "text"
    },
});
const data = await response.json();

Response

2004XX

{
  "expiry": "2024-11-21T06:28:59.658Z"
}

Keep Alive Session

For Launch Context-scoped streaming Sessions, indicates the Session is still in use, preventing it from being automatically expired and terminating the user's experience.

DELETEhttps://your-organization-id.m2worlds.io/api/sessions/{signedSessionId}/keepalive/

Authorization

BearerAuth

Path parameters

signedSessionId*string

The signed ID of a session for use with unauthenticated keep alive requests.

Header parameters

Response

2004XX

Returns the new expiry time of the session

Body

application/json

expiry*string (date-time)

The time the session expires

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/sessions/{signedSessionId}/keepalive/', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "x-m2-project-id": "text",
      "x-m2-launch-context-id": "text"
    },
});
const data = await response.json();

Response

2004XX

{
  "expiry": "2024-11-21T06:28:59.658Z"
}