sessions

Manages M2 streaming and native client sessions.

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

Default Response

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

launchContextId*string

The ID of a launch context

worldIdstring

The ID of a world

streamStatus*any of

The state of the session

enumenumenumenumenumenumenumenumenum

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

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-09-19T01:19:43.791Z",
    "startTime": "2024-09-19T01:19:43.791Z",
    "updateTime": "2024-09-19T01:19:43.791Z",
    "expiryTime": "2024-09-19T01:19:43.791Z",
    "failureReason": "text",
    "deletionReason": "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

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

Default Response

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

enumenumenumenumenumenumenumenumenum

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

Default Response

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

Default Response

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

launchContextId*string

The ID of a launch context

worldIdstring

The ID of a world

streamStatus*any of

The state of the session

enumenumenumenumenumenumenumenumenum

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

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-09-19T01:19:43.791Z",
  "startTime": "2024-09-19T01:19:43.791Z",
  "updateTime": "2024-09-19T01:19:43.791Z",
  "expiryTime": "2024-09-19T01:19:43.791Z",
  "failureReason": "text",
  "deletionReason": "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

Default Response

Body

application/json

sessionId*string

The ID of the session

state*any of

The state of the session

enumenumenumenumenumenumenumenumenum

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.

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

Authorization

BearerAuth

Path parameters

sessionId*string

The ID of the session

Header parameters

Response

404

Default Response

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-launch-context-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

Default Response

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
}

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

Default Response

Body

application/json

sessionId*string

The ID of the session

state*any of

The state of the session

enumenumenumenumenumenumenumenumenum

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",
      "x-m2-world-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

object

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",
      "x-m2-world-id": "text"
    },
});
const data = await response.json();

Response

2044XX

{}

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

Default Response

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-09-19T01:19:43.791Z"
}

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

Default Response

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-09-19T01:19:43.791Z"
}