Datasources

Manages ownership of virtual objects in a user's collection

List organization datasources

Fetches a list of all organization datasources for the specified organization. Accepts an optional type query parameter to filter by datasource type.

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

Authorization

BearerAuth

Query parameters

Header parameters

Response

200401

The response for GET /datasources

Body

application/json

itemsany of

A list of organization datasources. 'permissionVerb' indicates the permission level of the user on the datasource - Read (r), Write (w) or All (*)

OrganizationDatasourceWithReadPermissionSchema (object)OrganizationDatasourceWithWritePermissionsSchema (object)

Request

JavaScriptCurlPython

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

Response

200401

[
  {
    "name": "text",
    "type": "default",
    "hidden": false,
    "isPublic": false,
    "datasourceId": "text",
    "permissionVerb": "r"
  }
]

Create organization datasource

Creates a new organization datasource in the provided organization. Returns the id of the created datasource.

NOTE: Adding support for a new NFT contract in the platform requires work from the platform team and must be sent as a support request.

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

Authorization

BearerAuth

Body

application/json

name*string

The datasource's human readable name

typeenum

The type of the datasource - can either be 'undefined' or 'default'. WARNING: If set to 'default', objects created by users can be stored in this datasource. Not recommended unless this is the first datasource of the organization.

default

hiddenboolean

isPublicboolean

Whether the datasource is public. If true, all objects in this datasource will be available to all users of the organization.

Response

200400401403404

The response returned after creating an organization datasource

Body

application/json

datasourceId*string

Request

JavaScriptCurlPython

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

Response

200400401403404

{
  "datasourceId": "text"
}

Upsert MML Avatar

Create or update an MML Avatar ObjectDefinition with the provided assets ObjectDefinitions. Returns the Datasource ID and ObjectDefinition ID of the created/updated avatar. If avatar is provided, the specified ObjectDefinition will be validated and if it is an MML Avatar, the specified assets will overwrite the existing assets.

PUThttps://your-organization-id.m2worlds.io/api/datasources/avatars/

Authorization

BearerAuth

Body

application/json

avatarobject

The location of an avatar ObjectDefinition

assets*array of object

The assets that make up the avatar. Must contain at least 1 asset and at most 24 assets

namestring

The name of the created/updated MML Avatar. Must be between 1 and 64 characters

Response

200400401403404

The location of a created/updated avatar

Body

application/json

datasourceId*datasourceId (string)

The ID of a datasource

objectDefinitionId*objectDefinitionId (string)

The ID of an object definition

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/datasources/avatars/', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "assets": [
        {
          "datasourceId": "text",
          "objectDefinitionId": "text"
        }
      ]
    }),
});
const data = await response.json();

Response

200400401403404

{
  "datasourceId": "text",
  "objectDefinitionId": "text"
}

Get Collection

Get a user's collection. A collection is made up of multiple ObjectDefinitions that are aggregated from:

• Public Datasources in the organization
• Private Datasources in the organization
• NFT Datasources that have been enabled for the organization

A collection request can be filtered by properties, which will return only the ObjectDefinitions that match the root level of the specified properties.

GEThttps://your-organization-id.m2worlds.io/api/datasources/collections/

Authorization

BearerAuthApiKeyAuth

Query parameters

Header parameters

Response

200400

The response of the GET collections endpoint

Body

application/json

data*all of

originany of

The origin field is present for NFT ObjectDefinitions. It contains the NFT Contract Address, Token ID, and Chain ID the contract belongs to.

objectobject

uid*string

The unique ID of the ObjectDefinition. This is of the format datasourceId.objectDefinitionId

balance*number

Number of ObjectDefinitions the user has in their collection

isPublic*boolean

Whether the object is from a public datasource

Request

JavaScriptCurlPython

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

Response

200400

[
  {
    "data": {
      "name": "text",
      "description": "text",
      "image/jpeg": {
        "high": "https://example.com",
        "medium": "https://example.com",
        "low": "https://example.com",
        "original": "https://example.com"
      },
      "image/webp": {
        "original": "https://example.com"
      },
      "application/msquared+mml": {
        "original": "https://example.com"
      },
      "model/gltf-binary": {
        "original": "https://example.com"
      },
      "application/pdf": {
        "original": "https://example.com"
      },
      "audio/mpeg": {
        "original": "https://example.com"
      },
      "video/mp4": {
        "original": "https://example.com"
      },
      "properties": {
        "avatar": "",
        "avatarAsset": {
          "attachmentPoint": "head"
        }
      },
      "assets": [
        {
          "datasourceId": "text",
          "objectDefinitionId": "text"
        }
      ]
    },
    "origin": {
      "format": "contractAddressTokenId",
      "contractAddress": "text",
      "tokenId": "text",
      "chainId": "1"
    },
    "uid": "text",
    "balance": 0,
    "isPublic": false
  }
]

List properties

Returns a list of unique properties for a user's collection. Only the root level properties of each object are returned.

e.g. If a user's collection contains the following objects: [ { "data": { "name": "Alice", "properties": { "age": 30 } } }, { "data": { "name": "Bob", "properties": { "age": 25 "address": { "city": "New York", "state": "NY" } } } } ]

The response will be: ["address", "age"]. "city" and "state" are not included in the response because they are nested properties below the root level.

GEThttps://your-organization-id.m2worlds.io/api/datasources/collections/properties/

Authorization

BearerAuth

Header parameters

Response

200

The response of the GET collections properties endpoint

Body

application/json

itemsstring

Property name

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/datasources/collections/properties/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200

[
  "text"
]

Update organization datasource

Allows updating specific fields for an organization datasource.

PATCHhttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/

Authorization

BearerAuth

Path parameters

datasourceId*string

The ID of a datasource

Body

application/json

namestring

The datasource's human readable name

typeenum

The type of the datasource - can either be 'undefined' or 'default'. WARNING: If set to 'default', objects created by users can be stored in this datasource. Not recommended unless this is the first datasource of the organization.

default

hiddenboolean

isPublicboolean

Whether the datasource is public. If true, all objects in this datasource will be available to all users of the organization.

Response

200400401403404

Success

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

400401403404

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

Delete datasource

Deletes a datasource based on whether the X-M2-Organization-ID header is set:

• If present, it will process deletion of an organization datasource
• If not present, it will process deletion of an NFT datasource

DELETEhttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/

Authorization

BearerAuth

Path parameters

datasourceId*string

The ID of a datasource

Header parameters

Response

202400401403404

Success

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/', {
    method: 'DELETE',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

400401403404

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

Create Object Definition

Add a new Object Definition to the specified organization datasource. The request body should contain the object definition data and optionally a list of files to be uploaded. The request should be a multipart/form-data request.

POSThttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/

Authorization

BearerAuthApiKeyAuth

Path parameters

datasourceId*string

The ID of a datasource

Header parameters

Body

multipart/form-data

data*all of

mmlObjectstring

A raw MML string. Refer to https://mml.io/docs for how to create an MML string

filesany of

A file buffer or list of file buffers that represent a supported ObjectDefinition file type

array of anyany

propertiesstring

The stringified properties of an ObjectDefinition

Response

200400401403404503

The response body of POST organization datasource objectDefinition endpoint

Body

application/json

data*all of

id*string

The ID of an object definition

Request

JavaScriptCurlPython

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

Response

200400401403404503

{
  "data": {
    "name": "text",
    "description": "text",
    "image/jpeg": {
      "high": "https://example.com",
      "medium": "https://example.com",
      "low": "https://example.com",
      "original": "https://example.com"
    },
    "image/webp": {
      "original": "https://example.com"
    },
    "application/msquared+mml": {
      "original": "https://example.com"
    },
    "model/gltf-binary": {
      "original": "https://example.com"
    },
    "application/pdf": {
      "original": "https://example.com"
    },
    "audio/mpeg": {
      "original": "https://example.com"
    },
    "video/mp4": {
      "original": "https://example.com"
    },
    "properties": {
      "avatar": "",
      "avatarAsset": {
        "attachmentPoint": "head"
      }
    },
    "assets": [
      {
        "datasourceId": "text",
        "objectDefinitionId": "text"
      }
    ]
  },
  "id": "text"
}

List Object Definitions

Returns a list of all object definitions for the specified organization datasource.

GEThttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/

Authorization

BearerAuthApiKeyAuth

Path parameters

datasourceId*string

The ID of a datasource

Query parameters

Header parameters

Response

200400401403404

An array containing the object definitions for the given organization datasource

Body

application/json

data*all of

originany of

The origin field is present for NFT ObjectDefinitions. It contains the NFT Contract Address, Token ID, and Chain ID the contract belongs to.

objectobject

id*string

The ID of an object definition

Request

JavaScriptCurlPython

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

Response

200400401403404

[
  {
    "data": {
      "name": "text",
      "description": "text",
      "image/jpeg": {
        "high": "https://example.com",
        "medium": "https://example.com",
        "low": "https://example.com",
        "original": "https://example.com"
      },
      "image/webp": {
        "original": "https://example.com"
      },
      "application/msquared+mml": {
        "original": "https://example.com"
      },
      "model/gltf-binary": {
        "original": "https://example.com"
      },
      "application/pdf": {
        "original": "https://example.com"
      },
      "audio/mpeg": {
        "original": "https://example.com"
      },
      "video/mp4": {
        "original": "https://example.com"
      },
      "properties": {
        "avatar": "",
        "avatarAsset": {
          "attachmentPoint": "head"
        }
      },
      "assets": [
        {
          "datasourceId": "text",
          "objectDefinitionId": "text"
        }
      ]
    },
    "origin": {
      "format": "contractAddressTokenId",
      "contractAddress": "text",
      "tokenId": "text",
      "chainId": "1"
    },
    "id": "text"
  }
]

Delete all Object Definitions

Empties the specified organization datasource, deleting all object definitions stored in it. This will only work for non-default organization datasources.

DELETEhttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/

Authorization

BearerAuth

Path parameters

datasourceId*string

The ID of a datasource

Header parameters

Response

200400401403404

Success

Request

JavaScriptCurlPython

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

Response

400401403404

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

Get Object Definition

Retrieves the object definition if it exists for a given objectDefinitionId in a datasource. This can be used to query for an object definition across organization or NFT datasources.

GEThttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/{objectDefinitionId}/

Authorization

BearerAuthApiKeyAuth

Path parameters

datasourceId*datasourceId (string)

The ID of a datasource

objectDefinitionId*objectDefinitionId (string)

The ID of an object definition

Response

200401404

The shape of an ObjectDefinition

Body

application/json

data*all of

originany of

The origin field is present for NFT ObjectDefinitions. It contains the NFT Contract Address, Token ID, and Chain ID the contract belongs to.

objectobject

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/{objectDefinitionId}/', {
    method: 'GET',
    headers: {
      "Authorization": "Bearer <token>"
    },
});
const data = await response.json();

Response

200401404

{
  "data": {
    "name": "text",
    "description": "text",
    "image/jpeg": {
      "high": "https://example.com",
      "medium": "https://example.com",
      "low": "https://example.com",
      "original": "https://example.com"
    },
    "image/webp": {
      "original": "https://example.com"
    },
    "application/msquared+mml": {
      "original": "https://example.com"
    },
    "model/gltf-binary": {
      "original": "https://example.com"
    },
    "application/pdf": {
      "original": "https://example.com"
    },
    "audio/mpeg": {
      "original": "https://example.com"
    },
    "video/mp4": {
      "original": "https://example.com"
    },
    "properties": {
      "avatar": "",
      "avatarAsset": {
        "attachmentPoint": "head"
      }
    },
    "assets": [
      {
        "datasourceId": "text",
        "objectDefinitionId": "text"
      }
    ]
  },
  "origin": {
    "format": "contractAddressTokenId",
    "contractAddress": "text",
    "tokenId": "text",
    "chainId": "1"
  }
}

Update Object Definition

Updates an object definition in an organization datasource. Any existing object definition URLs will be overwritten with the new data provided in the request body.

PATCHhttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/{objectDefinitionId}/

Authorization

BearerAuth

Path parameters

datasourceId*datasourceId (string)

The ID of a datasource

objectDefinitionId*objectDefinitionId (string)

The ID of an object definition

Header parameters

Body

application/json

dataall of

originany of

The origin field is present for NFT ObjectDefinitions. It contains the NFT Contract Address, Token ID, and Chain ID the contract belongs to.

objectobject

Response

204400401403404

Success

Request

JavaScriptCurlPython

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

Response

400401403404

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

Delete Object Definition

Deletes an object definition from an organization datasource.

DELETEhttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/{objectDefinitionId}/

Authorization

BearerAuth

Path parameters

datasourceId*datasourceId (string)

The ID of a datasource

objectDefinitionId*objectDefinitionId (string)

The ID of an object definition

Header parameters

Response

204401403404

Success

Request

JavaScriptCurlPython

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

Response

401403404

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

List object definition owners

Retrieves a CSV file with the list of users who own the specified object definition in the datasource.

GEThttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/{objectDefinitionId}/userBalances/

Authorization

BearerAuth

Path parameters

datasourceId*datasourceId (string)

The ID of a datasource

objectDefinitionId*objectDefinitionId (string)

The ID of an object definition

Query parameters

Header parameters

Response

200

The response schema for the amount of a given object users have

Body

application/json

userId*string

walletAddressstring

balance*number

Request

JavaScriptCurlPython

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

Response

200

[
  {
    "userId": "text",
    "walletAddress": "text",
    "balance": 0
  }
]

Create Object Definitions

Allows creation of multiple object definitions for an organization datasource in a single request. You cannot upload any files in this request, hence valid URLs must be provided in the data field of each object definition in the request body.

The origin field is not applicable for this endpoint.

POSThttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/bulk/

Authorization

BearerAuthApiKeyAuth

Path parameters

datasourceId*string

The ID of a datasource

Header parameters

Body

application/json

data*all of

originany of

The origin field is present for NFT ObjectDefinitions. It contains the NFT Contract Address, Token ID, and Chain ID the contract belongs to.

objectobject

Response

201400401403404

Success

Request

JavaScriptCurlPython

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

Response

400401403404

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

Clear user balance

Sets a user's balance for the specified object definition in the organization datasource to 0. This means the user will no longer see that object in their collection.

This will not work for an object in a public organization datasource.

PUThttps://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/userBalances/delete/

Authorization

BearerAuth

Path parameters

datasourceId*string

The ID of a datasource

Body

application/json

objectDefinitionId*string

The ID of an object definition

Response

200400401404

Success

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/userBalances/delete/', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "objectDefinitionId": "text"
    }),
});
const data = await response.json();

Response

400401404

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

Enable/Disable NFT Datasource

Enable or disable an NFT Datasource for the organization. If an NFT Datasource is enabled, users in the organization will see the NFT ObjectDefinitions in their collection. If disabled, users will not see NFT ObjectDefinitions from the NFT Datasource in their collection.

If operation is ADD, the organization will support the NFT Datasource. If operation is REMOVE, the organization will no longer support the NFT Datasource, if already supported.

PATCHhttps://your-organization-id.m2worlds.io/api/datasources/external/

Authorization

BearerAuthApiKeyAuth

Header parameters

Body

application/json

List of datasourceId and operation pairs

datasourceId*string

The ID of a datasource

operation*any of

The operation to perform on the external datasource, either 'ADD' or 'REMOVE'

enumenum

Response

200400401403404

Success

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/datasources/external/', {
    method: 'PATCH',
    headers: {
      "Authorization": "Bearer <token>",
      "x-m2-organization-id": "text",
      "Content-Type": "application/json"
    },
    body: JSON.stringify([
      {
        "datasourceId": "text",
        "operation": 0
      }
    ]),
});
const data = await response.json();

Response

400401403404

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

Service health check

GEThttps://your-organization-id.m2worlds.io/api/datasources/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/datasources/healthz/', {
    method: 'GET',
    headers: {},
});
const data = await response.json();

Response

200

text

Refresh NFT balance

Triggers a NFT balance refresh for the calling user. The user's collection will be updated with the latest (supported) NFTs after a few seconds.

PUThttps://your-organization-id.m2worlds.io/api/datasources/nft/balance/refresh/

Authorization

BearerAuth

Body

application/json

refreshUserBalanceRequest (any of)

Request to refresh user balance

nullobject

Response

202401403

Success

Request

JavaScriptCurlPython

const response = await fetch('https://your-organization-id.m2worlds.io/api/datasources/nft/balance/refresh/', {
    method: 'PUT',
    headers: {
      "Authorization": "Bearer <token>",
      "Content-Type": "application/json"
    },
});
const data = await response.json();

Response

401403

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