Datasources

Manages ownership of virtual objects in a user's collection

Last updated 7 days ago

Was this helpful?

Get Collection

get

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.

Authorizations

Query parameters

uidstringoptional

The ID of a user

propertiesobjectoptional

The properties of an ObjectDefinition. Properties are key-value pairs where the key is always a string, and the value is either a string, boolean, integer, or another properties object. They can be nested.

Example: {"value":{"avatar":"","avatarAsset":{"attachmentPoint":"head"}}}

Header parameters

x-m2-organization-idstringoptional

The ID of an organization

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/collections/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

400

[
  {
    "data": "[Circular Reference]",
    "origin": {
      "format": "contractAddressTokenId",
      "contractAddress": "text",
      "tokenId": "text",
      "chainId": "1"
    },
    "uid": "text",
    "balance": 1,
    "isPublic": true
  }
]

The response of the GET collections endpoint

List properties

get

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.

Authorizations

Header parameters

x-m2-organization-idstringoptional

The ID of an organization

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/collections/properties/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

[
  "text"
]

The response of the GET collections properties endpoint

Delete datasource

delete

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

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Header parameters

x-m2-organization-idstringoptional

The ID of an organization

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

202

400

401

403

404

No body

Success

List Object Definitions

get

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

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Query parameters

limitnumberoptional

Number of documents to return per page

startAfterstringoptional

Unique id of the returned value object that the query should start after

endBeforestringoptional

Unique id of the returned value object that the query should end before

orderByobject[]optional

searchByobjectoptional

filterByobjectoptional

Filter by field and values. NOTE: This is not supported yet.

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'x-m2-organization-id: text'

200

400

401

403

404

[
  {
    "data": "[Circular Reference]",
    "origin": {
      "format": "contractAddressTokenId",
      "contractAddress": "text",
      "tokenId": "text",
      "chainId": "1"
    },
    "id": "text"
  }
]

An array containing the object definitions for the given organization datasource

Delete all Object Definitions

delete

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

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'x-m2-organization-id: text'

200

400

401

403

404

No body

Success

Get Object Definition

get

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.

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

objectDefinitionIdstringrequired

The ID of an object definition

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/{objectDefinitionId}/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

200

401

404

{
  "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": "[Circular Reference]",
    "assets": [
      {
        "datasourceId": "text",
        "objectDefinitionId": "text"
      }
    ],
    "tokenMetadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "origin": {
    "format": "contractAddressTokenId",
    "contractAddress": "text",
    "tokenId": "text",
    "chainId": "1"
  }
}

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

Delete Object Definition

delete

Deletes an object definition from an organization datasource.

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

objectDefinitionIdstringrequired

The ID of an object definition

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request DELETE \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/{objectDefinitionId}/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'x-m2-organization-id: text'

204

401

403

404

No body

Success

List object definition owners

get

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

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

objectDefinitionIdstringrequired

The ID of an object definition

Query parameters

limitnumberoptional

Number of documents to return per page

startAfterstringoptional

Unique id of the returned value object that the query should start after

endBeforestringoptional

Unique id of the returned value object that the query should end before

orderByobject[]optional

searchByobjectoptional

filterByobjectoptional

Filter by field and values. NOTE: This is not supported yet.

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/{objectDefinitionId}/userBalances/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'x-m2-organization-id: text'

200

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

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

List organization datasources

get

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

Authorizations

Query parameters

typestring · enumoptional

Options: default

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'x-m2-organization-id: text'

200

401

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

The response for GET /datasources

Create organization datasource

post

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.

Authorizations

Body

namestring · min: 1 · max: 64required

The datasource's human readable name

typestring · enumoptional

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.

Options: default

hiddenbooleanoptional

isPublicbooleanoptional

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "type": "default",
    "hidden": true,
    "isPublic": true
  }'

200

400

401

403

404

{
  "datasourceId": "text"
}

The response returned after creating an organization datasource

Upsert MML Avatar

put

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.

Authorizations

Body

avatarobjectoptional

The location of an avatar ObjectDefinition

assetsobject[] · min: 1 · max: 24required

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

namestring · min: 1 · max: 64optional

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/avatars/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "avatar": {
      "datasourceId": "text",
      "objectDefinitionId": "text"
    },
    "assets": [
      {
        "datasourceId": "text",
        "objectDefinitionId": "text"
      }
    ],
    "name": "text"
  }'

200

400

401

403

404

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

The location of a created/updated avatar

Update organization datasource

patch

Allows updating specific fields for an organization datasource.

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Body

namestring · min: 1 · max: 64optional

The datasource's human readable name

typestring · enumoptional

Options: default

hiddenbooleanoptional

isPublicbooleanoptional

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "text",
    "type": "default",
    "hidden": true,
    "isPublic": true
  }'

200

400

401

403

404

No body

Success

Create Object Definition

post

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.

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Body

all ofoptional

The request body of POST datasource objectDefinition endpoint

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'x-m2-organization-id: text' \
  --header 'Content-Type: multipart/form-data' \
  --form 'data=[object Object]' \
  --form 'mmlObject=text' \
  --form 'files=' \
  --form 'properties=text'

200

400

401

403

404

503

{
  "data": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "id": "text"
}

The response body of POST organization datasource objectDefinition endpoint

Update Object Definition

patch

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.

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

objectDefinitionIdstringrequired

The ID of an object definition

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Body

dataall ofoptional

originobjectoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/{objectDefinitionId}/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'x-m2-organization-id: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "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": "[Circular Reference]",
      "assets": [
        {
          "datasourceId": "text",
          "objectDefinitionId": "text"
        }
      ],
      "tokenMetadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "origin": {
      "format": "contractAddressTokenId",
      "contractAddress": "text",
      "tokenId": "text",
      "chainId": "1"
    }
  }'

204

400

401

403

404

No body

Success

Create Object Definitions

post

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.

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Body

dataall ofrequired

originobjectoptional

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/objectDefinitions/bulk/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'x-m2-organization-id: text' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "data": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "origin": {
        "format": "contractAddressTokenId",
        "contractAddress": "text",
        "tokenId": "text",
        "chainId": "1"
      }
    }
  ]'

201

400

401

403

404

No body

Success

Clear user balance

put

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.

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Body

objectDefinitionIdstringrequired

The ID of an object definition

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/{datasourceId}/userBalances/delete/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "objectDefinitionId": "text"
  }'

200

400

401

404

No body

Success

Enable/Disable NFT Datasource

patch

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.

Authorizations

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Body

datasourceIdstringrequired

The ID of a datasource

operationany ofrequired

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

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PATCH \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/external/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'x-m2-organization-id: text' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "datasourceId": "text",
      "operation": 0
    }
  ]'

200

400

401

403

404

No body

Success

Refresh NFT balance

put

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.

Authorizations

Body

any ofoptional

Request to refresh user balance

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request PUT \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/nft/balance/refresh/' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --header 'Content-Type: application/json'

202

401

403

No body

Success

Get Collection

Show child attributes

List properties

Delete datasource

List Object Definitions

Show child attributes

Show child attributes

Show child attributes

Delete all Object Definitions

Get Object Definition

Delete Object Definition

List object definition owners

Show child attributes

Show child attributes

Show child attributes

List organization datasources

Create organization datasource

Upsert MML Avatar

Show child attributes

Show child attributes

Update organization datasource

Create Object Definition

Show child attributes

Update Object Definition

Show child attributes

Show child attributes

Show child attributes

Create Object Definitions

Show child attributes

Show child attributes

Show child attributes

Clear user balance

Enable/Disable NFT Datasource

Show child attributes

Show child attributes

Refresh NFT balance

Show child attributes

Show child attributes