Datasources

Manages ownership of virtual objects in a user's collection

Last updated 4 months ago

Was this helpful?

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.

get

Authorizations

Query parameters

typestring · enum

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",
    "hidden": true,
    "isPublic": true,
    "datasourceId": "text",
    "type": "default",
    "permissionVerb": "r"
  }
]

The response for GET /datasources

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.

post

Authorizations

Body

namestring · min: 1 · max: 64required

The datasource's human readable name

hiddenboolean

isPublicboolean

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

typestring · enum

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

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"}'

200

400

401

403

404

{
  "datasourceId": "text"
}

The response returned after creating an organization datasource

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.

put

/avatars/

Authorizations

Body

namestring · min: 1 · max: 64

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

avatarobject

The location of an avatar ObjectDefinition

assetsobject[]required

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

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"}]}'

200

400

401

403

404

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

The location of a created/updated avatar

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.

get

/collections/

Authorizations

Query parameters

uidstring

The ID of a user

propertiesobject

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-idstring

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

[
  {
    "origin": {
      "contractAddress": "text",
      "tokenId": "text",
      "format": "contractAddressTokenId",
      "chainId": "1"
    },
    "data": {
      "name": "text",
      "description": "text",
      "properties": {
        "avatar": "",
        "avatarAsset": {
          "attachmentPoint": "head"
        }
      },
      "tokenMetadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "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"
      },
      "assets": [
        {
          "datasourceId": "text",
          "objectDefinitionId": "text"
        }
      ],
      "image/jpeg": {
        "high": "https://example.com",
        "medium": "https://example.com",
        "low": "https://example.com",
        "original": "https://example.com"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "uid": "text",
    "balance": 1,
    "isPublic": true
  }
]

The response of the GET collections endpoint

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.

get

/collections/properties/

Authorizations

Header parameters

x-m2-organization-idstring

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

Update organization datasource

Allows updating specific fields for an organization datasource.

patch

/{datasourceId}//

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Body

namestring · min: 1 · max: 64

The datasource's human readable name

hiddenboolean

isPublicboolean

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

typestring · enum

Options: default

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 '{"type":"default"}'

200

400

401

403

404

No body

Success

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

delete

/{datasourceId}//

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Header parameters

x-m2-organization-idstring

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

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.

post

/{datasourceId}/objectDefinitions/

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Body

dataall ofrequired

mmlObjectstring

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

propertiesstring

The stringified properties of an ObjectDefinition

filesany of

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

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' \
  --data '{"data":{"properties":{"avatar":"","avatarAsset":{"attachmentPoint":"head"}},"tokenMetadata":{"ANY_ADDITIONAL_PROPERTY":"anything"},"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"},"assets":[{"datasourceId":"text","objectDefinitionId":"text"}],"image/jpeg":{},"ANY_ADDITIONAL_PROPERTY":"anything"},"files":[]}'

200

400

401

403

404

503

{
  "data": {
    "name": "text",
    "description": "text",
    "properties": {
      "avatar": "",
      "avatarAsset": {
        "attachmentPoint": "head"
      }
    },
    "tokenMetadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "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"
    },
    "assets": [
      {
        "datasourceId": "text",
        "objectDefinitionId": "text"
      }
    ],
    "image/jpeg": {
      "high": "https://example.com",
      "medium": "https://example.com",
      "low": "https://example.com",
      "original": "https://example.com"
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "id": "text"
}

The response body of POST organization datasource objectDefinition endpoint

List Object Definitions

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

get

/{datasourceId}/objectDefinitions/

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Query parameters

limitnumber

Number of documents to return per page

startAfterstring

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

endBeforestring

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

orderByobject[]

searchByobject

filterByobject

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

[
  {
    "origin": {
      "contractAddress": "text",
      "tokenId": "text",
      "format": "contractAddressTokenId",
      "chainId": "1"
    },
    "data": {
      "name": "text",
      "description": "text",
      "properties": {
        "avatar": "",
        "avatarAsset": {
          "attachmentPoint": "head"
        }
      },
      "tokenMetadata": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "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"
      },
      "assets": [
        {
          "datasourceId": "text",
          "objectDefinitionId": "text"
        }
      ],
      "image/jpeg": {
        "high": "https://example.com",
        "medium": "https://example.com",
        "low": "https://example.com",
        "original": "https://example.com"
      },
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "id": "text"
  }
]

An array containing the object definitions for the given organization datasource

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.

delete

/{datasourceId}/objectDefinitions/

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

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.

get

/{datasourceId}/objectDefinitions/{objectDefinitionId}//

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

{
  "origin": {
    "contractAddress": "text",
    "tokenId": "text",
    "format": "contractAddressTokenId",
    "chainId": "1"
  },
  "data": {
    "name": "text",
    "description": "text",
    "properties": {
      "avatar": "",
      "avatarAsset": {
        "attachmentPoint": "head"
      }
    },
    "tokenMetadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "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"
    },
    "assets": [
      {
        "datasourceId": "text",
        "objectDefinitionId": "text"
      }
    ],
    "image/jpeg": {
      "high": "https://example.com",
      "medium": "https://example.com",
      "low": "https://example.com",
      "original": "https://example.com"
    },
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

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.

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.

patch

/{datasourceId}/objectDefinitions/{objectDefinitionId}//

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

originobject

dataall of

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 '{"origin":{"contractAddress":"text","tokenId":"text","format":"contractAddressTokenId","chainId":"1"},"data":{"properties":{"avatar":"","avatarAsset":{"attachmentPoint":"head"}},"tokenMetadata":{"ANY_ADDITIONAL_PROPERTY":"anything"},"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"},"assets":[{"datasourceId":"text","objectDefinitionId":"text"}],"image/jpeg":{},"ANY_ADDITIONAL_PROPERTY":"anything"}}'

204

400

401

403

404

No body

Success

Delete Object Definition

Deletes an object definition from an organization datasource.

delete

/{datasourceId}/objectDefinitions/{objectDefinitionId}//

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

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

get

/{datasourceId}/objectDefinitions/{objectDefinitionId}/userBalances/

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

objectDefinitionIdstringrequired

The ID of an object definition

Query parameters

limitnumber

Number of documents to return per page

startAfterstring

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

endBeforestring

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

orderByobject[]

searchByobject

filterByobject

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

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.

post

/{datasourceId}/objectDefinitions/bulk/

Authorizations

Path parameters

datasourceIdstringrequired

The ID of a datasource

Header parameters

x-m2-organization-idstringrequired

The ID of an organization

Body

originobject

dataall ofrequired

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 '[{"origin":{"contractAddress":"text","tokenId":"text","format":"contractAddressTokenId","chainId":"1"},"data":{"properties":{"avatar":"","avatarAsset":{"attachmentPoint":"head"}},"tokenMetadata":{"ANY_ADDITIONAL_PROPERTY":"anything"},"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"},"assets":[{"datasourceId":"text","objectDefinitionId":"text"}],"image/jpeg":{},"ANY_ADDITIONAL_PROPERTY":"anything"}}]'

201

400

401

403

404

No body

Success

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.

put

/{datasourceId}/userBalances/delete/

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

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.

patch

/external/

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

Service health check

get

/healthz/

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://your-organization-id.m2worlds.io/api/datasources/healthz/'

200

text

Provides information about the service status.

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.

put

/nft/balance/refresh/

Authorizations

Body

any of

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