Worlds
The Worlds service manages virtual environments, each defined by World Builder content with custom runtime settings (map selection, session duration, etc.).
Retrieves and returns all worlds that belong to the given Organization. Can also additionally filter by project if a project ID is passed in the headers.
The ID of an organization
The ID of a project
Lists all worlds for an organization or project (if specified)
GET /api/worlds/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
Accept: */*
Lists all worlds for an organization or project (if specified)
[
{
"documentId": "text",
"name": "text",
"description": "text",
"pictureUrl": "https://example.com",
"transient": true,
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"compute": {
"group": "production",
"region": "Europe",
"version": "text"
},
"networking": {
"strategy": "Default",
"scaling": {
"profile": "Capacity30",
"configuration": null
}
},
"runtime": {
"build": {
"channelId": "text",
"tag": "text",
"content": {
"id": "text"
}
},
"mapName": "text",
"durationMinutes": 1,
"capacity": 1,
"admissionPolicy": "Open"
},
"status": {
"phase": "Inactive",
"message": "text",
"startedAt": "text",
"resolvedBuild": {
"channelId": "text",
"tag": "text",
"organizationId": "text",
"id": "text"
},
"runId": "text"
},
"manifest": {
"serverPermissions": [
"text"
],
"clientPermissions": [
"text"
]
},
"admission": {
"policy": "Open",
"capacity": 1
},
"sessions": {
"controlPolicy": "Unlimited",
"streamingTicketPredicate": "text",
"flags": {
"ignoreExpiry": false,
"ignoreSlotRenewalErrors": false,
"ignoreParentMissing": false,
"useImmediateMode": false
},
"forceTravelWorldId": "text"
},
"organizationId": "text",
"projectId": "text",
"launchContext": {
"launchContextId": "text",
"name": "text",
"isActive": true,
"publicDownload": {
"enabled": true,
"enforceAntiCheat": true,
"allowMac": true,
"allowIos": true
},
"isWorldTravelOnly": true,
"worldId": "text",
"description": "text",
"errorPageUrl": "text",
"okPageUrl": "text",
"gdnStreaming": {
"cmsId": "text",
"authorizationId": "text",
"launchMode": "same-tab",
"useCustomClient": true,
"useWindowedMode": true
},
"ubitusStreaming": {
"gameLabel": "text",
"gameChannel": "text"
},
"streamManager": {
"streamContextId": "text",
"allowForceProvider": true,
"showProviderOptions": true,
"useBuildVersion": true
},
"bypassBrowserRestrictions": true,
"enableQueue": true,
"capacity": 1,
"buildInfo": {
"buildChannelId": "text",
"buildTag": "text",
"buildType": "client"
},
"splashScreenUrl": "text",
"deployment": {
"region": "text",
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"version": "text"
},
"useWorldSessions": true,
"pictureUrl": "text",
"isPublic": true,
"organizationId": "text",
"projectId": "text",
"artifactUrl": "text",
"permissionVerb": "*"
},
"queueState": null
}
]
Creates a world in the given Organization and Project. Checks if the user can create a world with the given size.
The ID of an organization
The ID of a project
The new world's details
The name of a world
^.+\S.*$
The description of a world
The picture URL of a world
Describes whether the world is transient. Transient worlds are automatically deleted once their duration expires and they are fully stopped.
The world's ID, if created successfully
POST /api/worlds/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Content-Type: application/json
Accept: */*
Content-Length: 1142
{
"streaming": {
"gdn": {
"cmsId": "text",
"authorizationId": "text",
"launchMode": "same-tab",
"useCustomClient": true,
"useWindowedMode": true
},
"streamManager": {
"streamContextId": "text",
"allowForceProvider": true,
"showProviderOptions": true,
"useBuildVersion": true
},
"ubitus": {
"gameLabel": "text",
"gameChannel": "text"
}
},
"compute": {
"group": "production",
"region": "Europe",
"version": "text"
},
"networking": {
"strategy": "Default",
"scaling": {
"profile": "Capacity30",
"configuration": null
}
},
"runtime": {
"mapName": "text",
"durationMinutes": 1,
"capacity": 1,
"admissionPolicy": "Open",
"build": {
"channelId": "text",
"tag": "text",
"content": {
"id": "text"
}
}
},
"name": "text",
"description": "text",
"pictureUrl": "https://example.com",
"transient": true,
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"manifest": {
"serverPermissions": [
"text"
],
"clientPermissions": [
"text"
]
},
"admission": {
"policy": "Open",
"capacity": 1
},
"sessions": {
"controlPolicy": "Unlimited",
"streamingTicketPredicate": "text",
"flags": {
"ignoreExpiry": false,
"ignoreSlotRenewalErrors": false,
"ignoreParentMissing": false,
"useImmediateMode": false
},
"forceTravelWorldId": "text"
}
}
The world's ID, if created successfully
{
"worldId": "text",
"launchContextId": "text"
}
List of worlds that the client can launch into
The error object returned by the API when an error occurs
GET /api/worlds/travel/locations/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"worlds": [
{
"deployment": "text",
"map": "text",
"buildId": "text",
"organizationId": "text",
"projectId": "text",
"launchContextId": "text",
"launchContextName": "text",
"worldId": "text",
"worldName": "text",
"liveConfigUrl": "text",
"contentId": "text",
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
}
]
}
Retrieves and returns the specified world and linked launch context.
The ID of a world
The ID of an organization
The ID of a project
The details for a world
The error object returned by the API when an error occurs
GET /api/worlds/{worldId}/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
{
"documentId": "text",
"name": "text",
"description": "text",
"pictureUrl": "https://example.com",
"transient": true,
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"compute": {
"group": "production",
"region": "Europe",
"version": "text"
},
"networking": {
"strategy": "Default",
"scaling": {
"profile": "Capacity30",
"configuration": null
}
},
"runtime": {
"build": {
"channelId": "text",
"tag": "text",
"content": {
"id": "text"
}
},
"mapName": "text",
"durationMinutes": 1,
"capacity": 1,
"admissionPolicy": "Open"
},
"status": {
"phase": "Inactive",
"message": "text",
"startedAt": "text",
"resolvedBuild": {
"channelId": "text",
"tag": "text",
"organizationId": "text",
"id": "text"
},
"runId": "text"
},
"manifest": {
"serverPermissions": [
"text"
],
"clientPermissions": [
"text"
]
},
"admission": {
"policy": "Open",
"capacity": 1
},
"sessions": {
"controlPolicy": "Unlimited",
"streamingTicketPredicate": "text",
"flags": {
"ignoreExpiry": false,
"ignoreSlotRenewalErrors": false,
"ignoreParentMissing": false,
"useImmediateMode": false
},
"forceTravelWorldId": "text"
},
"organizationId": "text",
"projectId": "text",
"launchContext": {
"launchContextId": "text",
"name": "text",
"isActive": true,
"publicDownload": {
"enabled": true,
"enforceAntiCheat": true,
"allowMac": true,
"allowIos": true
},
"isWorldTravelOnly": true,
"worldId": "text",
"description": "text",
"errorPageUrl": "text",
"okPageUrl": "text",
"gdnStreaming": {
"cmsId": "text",
"authorizationId": "text",
"launchMode": "same-tab",
"useCustomClient": true,
"useWindowedMode": true
},
"ubitusStreaming": {
"gameLabel": "text",
"gameChannel": "text"
},
"streamManager": {
"streamContextId": "text",
"allowForceProvider": true,
"showProviderOptions": true,
"useBuildVersion": true
},
"bypassBrowserRestrictions": true,
"enableQueue": true,
"capacity": 1,
"buildInfo": {
"buildChannelId": "text",
"buildTag": "text",
"buildType": "client"
},
"splashScreenUrl": "text",
"deployment": {
"region": "text",
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"version": "text"
},
"useWorldSessions": true,
"pictureUrl": "text",
"isPublic": true,
"organizationId": "text",
"projectId": "text",
"artifactUrl": "text",
"permissionVerb": "*"
}
}
Updates the specified world and returns the resulting new world data if successful.
The ID of a world
The ID of an organization
The ID of a project
The world details to update. Partial updates of object fields are not allowed. All nested fields must be provided and optional fields will be reset to default.
The name of a world
^.+\S.*$
The description of a world
The updated world details
Default Response
The error object returned by the API when an error occurs
PATCH /api/worlds/{worldId}/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Content-Type: application/json
Accept: */*
Content-Length: 906
{
"streaming": {
"gdn": {
"cmsId": "text",
"authorizationId": "text",
"launchMode": "same-tab",
"useCustomClient": true,
"useWindowedMode": true
},
"streamManager": {
"streamContextId": "text",
"allowForceProvider": true,
"showProviderOptions": true,
"useBuildVersion": true
},
"ubitus": {
"gameLabel": "text",
"gameChannel": "text"
}
},
"name": "text",
"description": "text",
"pictureUrl": "https://example.com",
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"compute": {
"group": "production",
"region": "Europe",
"version": "text"
},
"networking": {
"strategy": "Default",
"scaling": {
"profile": "Capacity30",
"configuration": null
}
},
"runtime": {
"build": {
"channelId": "text",
"tag": "text",
"content": {
"id": "text"
}
},
"mapName": "text",
"durationMinutes": 1,
"capacity": 1,
"admissionPolicy": "Open"
},
"manifest": {
"serverPermissions": [
"text"
],
"clientPermissions": [
"text"
]
},
"admission": {
"policy": "Open",
"capacity": 1
}
}
{
"documentId": "text",
"name": "text",
"description": "text",
"pictureUrl": "https://example.com",
"transient": true,
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"compute": {
"group": "production",
"region": "Europe",
"version": "text"
},
"networking": {
"strategy": "Default",
"scaling": {
"profile": "Capacity30",
"configuration": null
}
},
"runtime": {
"build": {
"channelId": "text",
"tag": "text",
"content": {
"id": "text"
}
},
"mapName": "text",
"durationMinutes": 1,
"capacity": 1,
"admissionPolicy": "Open"
},
"status": {
"phase": "Inactive",
"message": "text",
"startedAt": "text",
"resolvedBuild": {
"channelId": "text",
"tag": "text",
"organizationId": "text",
"id": "text"
},
"runId": "text"
},
"manifest": {
"serverPermissions": [
"text"
],
"clientPermissions": [
"text"
]
},
"admission": {
"policy": "Open",
"capacity": 1
},
"sessions": {
"controlPolicy": "Unlimited",
"streamingTicketPredicate": "text",
"flags": {
"ignoreExpiry": false,
"ignoreSlotRenewalErrors": false,
"ignoreParentMissing": false,
"useImmediateMode": false
},
"forceTravelWorldId": "text"
}
}
Deletes the specified world.
The ID of a world
The ID of an organization
The ID of a project
Empty response
Empty response
The error object returned by the API when an error occurs
DELETE /api/worlds/{worldId}/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
No content
Get all bot deployments for the specified world
The ID of a world
The ID of an organization
The ID of a project
All bot deployments for a world
The error object returned by the API when an error occurs
GET /api/worlds/{worldId}/bots/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
[
{
"documentId": "text",
"description": "text",
"configuration": {
"count": 1,
"cpu": "/[a-z]/",
"memory": "/[a-z]/",
"args": [
"text"
],
"durationMinutes": 1
},
"status": {
"phase": "Pending",
"message": "text",
"startedAt": 1,
"worldStartedAt": "text",
"cluster": {
"name": "text",
"computeGroup": "text"
}
},
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"organizationId": "text",
"projectId": "text",
"worldId": "text"
}
]
Create a bot deployment for the specified world with the provided bot count
The ID of a world
The ID of an organization
The ID of a project
Create a bot deployment
^\d+(m|\.\d\d?\d?)?$
^\d+(\.\d+)?(m|k|Ki|M|Mi|G|Gi)?$
Default Response
POST /api/worlds/{worldId}/bots/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Content-Type: application/json
Accept: */*
Content-Length: 209
{
"description": "text",
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"count": 1,
"cpu": "/[a-z]/",
"memory": "/[a-z]/",
"args": [
"text"
],
"durationMinutes": 1
}
Default Response
No content
Get the details for a specific bot deployment for the specified world.
The ID of a world
The ID of a bot deployment
The ID of an organization
The ID of a project
The details for a bot deployment
The error object returned by the API when an error occurs
GET /api/worlds/{worldId}/bots/{botDeploymentId}/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
{
"documentId": "text",
"description": "text",
"configuration": {
"count": 1,
"cpu": "/[a-z]/",
"memory": "/[a-z]/",
"args": [
"text"
],
"durationMinutes": 1
},
"status": {
"phase": "Pending",
"message": "text",
"startedAt": 1,
"worldStartedAt": "text",
"cluster": {
"name": "text",
"computeGroup": "text"
}
},
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"organizationId": "text",
"projectId": "text",
"worldId": "text"
}
Update a bot deployment for the specified world. This can be used to alter the bot count in a bot deployment.
The ID of a world
The ID of a bot deployment
The ID of an organization
The ID of a project
Patch a bot deployment
^\d+(m|\.\d\d?\d?)?$
^\d+(\.\d+)?(m|k|Ki|M|Mi|G|Gi)?$
Default Response
PATCH /api/worlds/{worldId}/bots/{botDeploymentId}/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Content-Type: application/json
Accept: */*
Content-Length: 188
{
"count": 1,
"cpu": "/[a-z]/",
"memory": "/[a-z]/",
"args": [
"text"
],
"durationMinutes": 1,
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
}
Default Response
No content
Stop a bot deployment for the specified world
The ID of a world
The ID of a bot deployment
The ID of an organization
The ID of a project
Default Response
DELETE /api/worlds/{worldId}/bots/{botDeploymentId}/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
Default Response
No content
Returns the specified world's deployments. Optionally can be filtered by status, provided in the query string.
The ID of a world
The ID of an organization
The ID of a project
Details for the World's deployments
The error object returned by the API when an error occurs
GET /api/worlds/{worldId}/deployments/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
[
{
"organizationId": "text",
"projectId": "text",
"worldId": "text",
"runId": "text",
"createdAt": "text",
"id": "text",
"networking": {
"scaling": {
"profile": "Capacity30"
}
},
"externalId": "text",
"compute": {
"clusterName": "text",
"group": "production",
"region": "Europe",
"version": "text"
},
"runtime": {
"build": {
"channelId": "text",
"id": "text",
"content": {
"id": "text"
}
},
"mapName": "text",
"liveConfigUrl": "text",
"durationMinute": 1,
"args": [
"text"
]
},
"status": "Unknown"
}
]
Update the picture URL of a world
The ID of a world
The ID of an organization
The ID of a project
The updated world details
The error object returned by the API when an error occurs
The error object returned by the API when an error occurs
The error object returned by the API when an error occurs
PATCH /api/worlds/{worldId}/pictureUrl/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
{
"documentId": "text",
"name": "text",
"description": "text",
"pictureUrl": "https://example.com",
"transient": true,
"metadata": {
"annotations": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"labels": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
},
"compute": {
"group": "production",
"region": "Europe",
"version": "text"
},
"networking": {
"strategy": "Default",
"scaling": {
"profile": "Capacity30",
"configuration": null
}
},
"runtime": {
"build": {
"channelId": "text",
"tag": "text",
"content": {
"id": "text"
}
},
"mapName": "text",
"durationMinutes": 1,
"capacity": 1,
"admissionPolicy": "Open"
},
"status": {
"phase": "Inactive",
"message": "text",
"startedAt": "text",
"resolvedBuild": {
"channelId": "text",
"tag": "text",
"organizationId": "text",
"id": "text"
},
"runId": "text"
},
"manifest": {
"serverPermissions": [
"text"
],
"clientPermissions": [
"text"
]
},
"admission": {
"policy": "Open",
"capacity": 1
},
"sessions": {
"controlPolicy": "Unlimited",
"streamingTicketPredicate": "text",
"flags": {
"ignoreExpiry": false,
"ignoreSlotRenewalErrors": false,
"ignoreParentMissing": false,
"useImmediateMode": false
},
"forceTravelWorldId": "text"
}
}
Returns a list of all active roles for a world. Could be used to get all possible conditions that allow a user to access a world.
The ID of a world
The ID of an organization
The ID of a project
The roles that can access a world
GET /api/worlds/{worldId}/roles/ HTTP/1.1
Host: your-organization-id.m2worlds.io
Authorization: Bearer YOUR_SECRET_TOKEN
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
The roles that can access a world
[
{
"roleId": "text",
"name": "text",
"groupCondition": {
"identifiers": [
"text"
],
"conditionType": "allUsers",
"isActive": true,
"expiryDate": {
"to": "text",
"from": "text"
},
"capacity": 1,
"guestToken": "text",
"chainId": "1"
}
}
]
Transitions the phase of the world to Starting, which will subsequently launch the underlying deployments. With this transition, the world run ID and startedAt timestamp are reset.
The ID of a world
The ID of an organization
The ID of a project
Empty response
Empty response
The error object returned by the API when an error occurs
POST /api/worlds/{worldId}/start/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
No content
Transition the world phase to Stopped, which subsequently stops underlying deployments.
The ID of a world
The ID of an organization
The ID of a project
Empty response
Empty response
The error object returned by the API when an error occurs
POST /api/worlds/{worldId}/stop/ HTTP/1.1
Host: your-organization-id.m2worlds.io
x-api-key: YOUR_API_KEY
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
No content
The ID of a world
The ID of a user
The ID of an organization
The ID of a project
Indicates if a user has access to a world
HTTP error message
GET /api/worlds/{worldId}/users/{userId}/access/ HTTP/1.1
Host: your-organization-id.m2worlds.io
Authorization: Bearer YOUR_SECRET_TOKEN
x-m2-organization-id: text
x-m2-project-id: text
Accept: */*
{
"userId": "text",
"hasAccess": true
}
Last updated
Was this helpful?