logo
API docs by Redocly

API Specification for the Decentraland Catalyst Server (BETA) (1.0)

Download OpenAPI specification:Download

License: Apache 2.0

A Catalyst is a Server that runs different services. These services currently work as the backbone for Decentraland and work in a decentralized network. The current specification details the following services:

- Archipelago
- Content Server
- Lambdas Service

WARNING: We are working to close the version 1.0 of the Catalyst Protocol defined by this API. So far this is what we have and it's public but we are still working on refinement and during this process we may decided to deprecate or change some of the endpoints.

Global

Endpoints that are about the whole catalyst or about shared services

Catalyst Server Configs and health

Retrieve detailed information about the services health and its configuration

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "healthy": true,
  • "configurations": {
    },
  • "content": {
    },
  • "comms": {
    },
  • "lambdas": {
    },
  • "bff": {
    }
}

The stats from all parcels

Retrieves the amount of users on each parcel

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "parcels": [
    ]
}

Content Server

Decentraland is a virtual world that is owned by its users. One of the biggest differentiators about Decentraland is its level of decentralization. Users can own LAND, wearables, and probably other types of items in the future. Each of these items is an NFT in itself, and therefore ownership is determined by the Ethereum (or EVM-compatible) blockchain.

Now, when a new wearable is created, or when a user uploads a scene to their LAND/parcel, all necessary files (3d models, textures, music, etc) are uploaded to a "content server". Why are we using these servers instead of the blockchain? Mainly because it would be prohibitively expensive to store files as big as 3d models in the blockchain. Users would have to pay fees so high to upload content to their parcels that nobody would do it.

So this is where content servers come into play. The content server is mainly a server where users can upload these files we mentioned before. Each server will verify against the blockchain that the user making the upload is actually allowed to do so. For example, in the case of scenes, the server will check that the deployer owns all the parcels they are trying to modify.

And the most important part is that all content servers will then sync with each other. So, for example, if a scene is modified in one server, the update itself will be broadcasted to the other ones. Then, in the case a content server goes down for some reason, all content will still be present in the other ones.

Get information about an entity

Get information about an entity, such us Scenes Profiles or Wearables, with the specified entityId.

path Parameters
entityType
required
string
Enum: "profile" "scene" "wearable"
Example: profile

Specify the type of entity to audit

entityId
required
string
Example: QmQgezF4UWTZpD5VqKs2AGCzucRJdm8zU87MxdSRH9heZR

id of the entity

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "version": "v3",
  • "localTimestamp": 1628271052660,
  • "authChain": [
    ]
}

Validate if the Server is part of the DAO

Used by the Server to figure out their identity on the DAO by themselves, so they will generate a random challenge text, and then query each server for it. If the text matches, then they have found themselves.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "challengeText": "186a1c51-2c4c-4dae-913c-b87670600c56"
}

Download content file

Download the binary file associated with the specified hashId

path Parameters
hashId
required
string
Example: QmVzr55TyXcrbQUWBN6rf7K7zkZsTFnBK19LvgYM9CxFbu

Hash of the file to be retrieved, you can search for the hashId in the content section of a deployment. If the entity version greater than or equal to v4, then the hashing algorithm will be IPFS, if the entity version is v3 or below then it will be SHA-256

Responses

Response samples

Content type
application/json; charset=utf-8
"Not Found"

Check if a content file exists

Check if a content file exists

path Parameters
hashId
required
string
Example: QmVzr55TyXcrbQUWBN6rf7K7zkZsTFnBK19LvgYM9CxFbu

Hash of the file to be checked

Responses

Response samples

Content type
application/json; charset=utf-8
"Not Found"

List of entityIds associated with a hashId

Get the list of entity ids whose deployments are associated with the specified content hash. This endpoint is currently intended for troubleshooting as there is no specific use case for it.

path Parameters
hashId
required
string
Example: QmWFLwHGfvhB9a1epaRpS38HEwbHvhpaYzHEsNhDRgon7P

Hash of the content file

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • "QmY4GFuf2jR3ocfuXuFLgvUrGEpjo84Byg44Pv2wduuinW",
  • "QmZbAEFPF7LSq9xVZTCAZoHPNV1QX7YiSbKL2g881MJLj8"
]

Validates if file exists on the Server

Given a list of hashes, validates if the corresponding files exist in the storage of the server

query Parameters
cid
required
Array of strings
Example: cid=QmWFLwHGfvhB9a1epaRpS38HEwbHvhpaYzHEsNhDRgon7P

Hash of the content file

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    },
  • {
    }
]

Deploys an entity

Deploys an entity in the content server. This request must contain a file with the entity itself and also the files associated with it, such as 3D models, as well as information about the entity and requester. This request will succeed only if the hash of the entity file matches the entityId and also if the signature is valid has the correct permission to modify the pointers associated with it.

Request Body schema: multipart/form-data
files
Array of strings <binary>
entityId
string
authChain
string
ethAddress
string
signature
string

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "creationTimestamp": 1628607669304
}

List of active entities matching urn prefix

Returns the list of active entities which have at least one pointer that matches the prefix given

path Parameters
collectionUrn
required
string
Example: urn:decentraland:matic:collections-v2:0x8e674db9b2fc0759b2d94cace9c4bae334a8f0c3

urn prefix to filter the entities by

query Parameters
pageSize
number

Page size (max 1000)

pageNumber
number

Page number (default: 1)

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    },
  • {
    },
  • {
    }
]

List active entities by pointers or ids

Returns the list of entities of the specified type with the specified id or pointers. Only one of these filters must be specified in the body.

Request Body schema: application/json
pointers
Array of strings

Entities must be filtered by pointer XOR entityId (ids). Use this parameter if you want to retrieve an entity of the specified type with this pointer.

ids
Array of strings

Entities must be filtered by pointer (pointers) XOR entityId. Use this parameter if you want to retrieve an entity of the specified type with this entityId.

Responses

Request samples

Content type
application/json
{
  • "pointers": [
    ],
  • "ids": [
    ]
}

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

List of failed deployments

Retrieves a list of the failed deployments

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

List of changes made to a pointer

List of all deltas from the deployments inside the filters that affect the given pointers. It returns a list of changes with the before field (the entity that was overridden with this deployment) and after (the entity that overrides the current one if present).

query Parameters
from
integer
Example: from=1606829553969

Acts as a filter in the collection of deployments, this value is the minimum value of local timestamp that any deployment in the collection will have.

to
integer
Example: to=1606829553969

Acts as a filter in the collection of deployments, this value is the maximum value of local timestamp that any deployment in the collection will have.

lastId
string
Example: lastId=QmNknKv8MuKbfZ73z4QdUEsNbTd1ZAN1fSuwTFGiNGeCt5

It is the last entity id that was visited, so it will be skipped when showing current page.

limit
integer
Example: limit=100

The deployments are a paginated collection, this parameter corresponds to the limit for each page. The default value is 500.

entityType
string
Enum: "scene" "profile" "wearable"
Example: entityType=profile

The type of entities that will be shown in the collection, many values can be sent. Valid values are: profile, scene and wearable.

sortingField
string
Enum: "local_timestamp" "entity_timestamp"
Example: sortingField=local_timestamp

This value is used as the field to order all the deployments in the collection. If no parameter is sent, then the default field to order with will be local_timestamp.

sortingOrder
string
Enum: "ASC" "DESC"
Example: sortingOrder=ASC

This value is used as the order for all the deployments in the collection. If no parameter is sent, then the default field to order with will be DESC.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "deltas": [
    ]
}

Snapshots with a list of active entities

Lists all active deployments stored in the database in multiple snapshots for different time ranges. If the information needed is front in time of the most recent snapshot, you may use the /content/pointer-changes endpoint with the necessary from filter.

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    },
  • {
    }
]

Content Server status

Retrieve deteailed information about the content server status

Responses

Response samples

Content type
application/json; charset=utf-8
{}

Archipelago

This service is in charge of clustering users according to their position and assigning a connection string that will allow the user to connect to an specifig transport.

List of islands

Retrieves the list of communication islands in the server with details about the peers present in each island.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "ok": true,
  • "islands": [
    ]
}

Island Details

Retrieve information about the specified islandId

path Parameters
islandId
required
string
Example: I5n

ID of the Island. You can search for the list of islands using the /comms/islands endpoint.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "id": "I5n",
  • "peers": [
    ],
  • "maxPeers": 100,
  • "center": [
    ],
  • "radius": 0
}

List of peers

Retrieves the list peers in the server with details about their positions and islands.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "ok": true,
  • "peers": [
    ]
}

Lambdas

This service provides a set of utilities required by the Catalyst Server Clients\Consumers in order to retrieve or validate data.

Catalyst Server status

Retrieve detailed information about the services

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "version": "1.0",
  • "currentTime": 1628875330839,
  • "contentServerUrl": "https://peer.decentraland.org/content/",
  • "commitHash": "7890de4598f88a382863ea5f399b9cc17b80b42e",
  • "catalystVersion": "1.3.3"
}

Get Collections

Retrieve the list of collections URNs

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "collections": [
    ]
}

Download thumbnail image

Downloads a thumbnail image for the specified urn

path Parameters
urn
required
string
Example: urn:decentraland:matic:collections-v2:0x04e43281f36e1f1bfae6f38bc276cb48fb8ac632:0

Uniform Resource Name (URN) that identifies the asset

Responses

Download URN image

Downloads the image for the specified urn

path Parameters
urn
required
string
Example: urn:decentraland:matic:collections-v2:0x04e43281f36e1f1bfae6f38bc276cb48fb8ac632:0

Uniform Resource Name (URN) that identifies the asset

Responses

Get ERC721 Entity

Retrieve ERC721/NFT Entity details

path Parameters
chainId
required
string
Example: 137

Ethereum chain ID: ETHEREUM_MAINNET = 1 ETHEREUM_RINKEBY = 4 ETHEREUM_GOERLI = 5 ETHEREUM_KOVAN = 42 MATIC_MAINNET = 137 MATIC_MUMBAI = 80001

contract
required
string
Example: 0x123db7844eaf7da11d88cf1754945bbd020742ef

Hash of the Contract. This will be used to build the URN that identifies the NFT.

option
required
string
Example: 3

Token Identifier

emission
required
string
Example: legendary

Optional rarity description that will be return as part of the NFT description common: 100000 uncommon: 10000 rare: 5000 epic: 1000 legendary: 100 mythic: 10 unique: 1

Responses

Response samples

Content type
application/json; charset=utf-8
{}

Get list of wearables for an address

Get a list of wearables owned by the given address

path Parameters
address
required
string
Example: 0xa87d168717538e86d71ac48baccaeb84162de602

Ethereum address from which you want to get the list of wearables

query Parameters
includeEntities
boolean
Example: includeEntities=true

If present, response will be extended with the entity data.

includeThirdParty
boolean
Example: includeThirdParty=true

If present, response will include the third-party wearables owned by the address. They will appear before other wearables if the response is paginated.

pageNum
string
Example: pageNum=1

The number of the requested page.

pageSize
string
Example: pageSize=10

The size of the requested page.

orderBy
string
Example: orderBy=rarity

Determines the field to be sort by. By default it will be by transferredAt. Possible values: transferredAt and rarity.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "elements": [
    ],
  • "totalAmount": 23,
  • "pageNum": "2",
  • "pageSize": "4"
}

Get list of emotes for an address

Get a list of emotes owned by the given address

path Parameters
address
required
string
Example: 0xf4f7512c68f358856514cd4e449fc6c5ac04bb15

Ethereum address from which you want to get the list of emotes

query Parameters
collectionId
string
Example: collectionId=urn:decentraland:matic:collections-thirdparty:ntr1-meta:ntr1-meta-1ef79e7b

Third Party collection Id to filter emotes, if this param is not sent then the 3rd parties emotes are not shown. If it is sent, only the 3rd parties emotes are shown.

includeEntities
boolean
Example: includeEntities=true

If present, response will be extended with the entity data.

pageNum
string
Example: pageNum=1

The number of the requested page.

pageSize
string
Example: pageSize=10

The size of the requested page

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "elements": [
    ],
  • "totalAmount": 973,
  • "pageNum": "3",
  • "pageSize": "4"
}

Get list of names for an address

Get a list of names owned by the given address

path Parameters
address
required
string
Example: 0xddf1eec586d8f8f0eb8c5a3bf51fb99379a55684

Ethereum address from which you want to get the list of names

query Parameters
pageNum
string
Example: pageNum=1

The number of the requested page. It needs pageSize to be present to enable a paginated response.

pageSize
string
Example: pageSize=10

The size of the requested page. It needs pageNum to be present to enable a paginated response.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "names": [
    ],
  • "totalAmount": 812,
  • "pageNum": "2",
  • "pageSize": "4"
}

Get list of lands for an address

Get a list of lands owned by the given address

path Parameters
address
required
string
Example: 0xddf1eec586d8f8f0eb8c5a3bf51fb99379a55684

Ethereum address from which you want to get the list of lands

query Parameters
pageNum
string
Example: pageNum=1

The number of the requested page. It needs pageSize to be present to enable a paginated response.

pageSize
string
Example: pageSize=10

The size of the requested page. It needs pageNum to be present to enable a paginated response.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "lands": [
    ],
  • "totalAmount": 692,
  • "pageNum": "1",
  • "pageSize": "2"
}

Returns the list of third party wearables for the provided address

Returns the list of third party wearables for the provided address

path Parameters
address
required
string
Example: 0xf4f7512c68f358856514cd4e449fc6c5ac04bb15

Ethereum address from which you want to get the list of wearables

query Parameters
pageNum
string
Example: pageNum=1

The number of the requested page.

pageSize
string
Example: pageSize=10

The size of the requested page.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "elements": [
    ],
  • "totalAmount": 0,
  • "pageNum": 0,
  • "pageSize": 0
}

Returns the list of third party wearables for the given collection

Returns the list of third party wearables for the given collection

path Parameters
address
required
string
Example: 0xf4f7512c68f358856514cd4e449fc6c5ac04bb15

Ethereum address from which you want to get the list of wearables

collectionId
required
string
Example: urn:decentraland:matic:collections-thirdparty:ntr1-meta:ntr1-meta-1ef79e7b

Third Party collection Id to filter wearables.

query Parameters
pageNum
string
Example: pageNum=1

The number of the requested page.

pageSize
string
Example: pageSize=10

The size of the requested page.

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "elements": [
    ],
  • "totalAmount": 0,
  • "pageNum": 0,
  • "pageSize": 0
}

Search Wearables Deprecated

Search for wearables based on the applied filters and retrieve detailed information

query Parameters
collectionId
Array of strings
Example: collectionId=urn:decentraland:ethereum:collections-v1:mf_sammichgamer

Lis of URNs that identify the collection. Maximum amount of ids allowed is 500.

wearableId
Array of strings
Example: wearableId=urn:decentraland:ethereum:collections-v1:binance_us_collection:binance_us_hat

List of wearables URNs to search. Maximum amount of ids allowed is 500.

textSearch
string
Example: textSearch=Hoodie

Search text

limit
integer
Example: limit=2

Limit the quantity of results that will be returned by the request. You can only request up to 500 results.

lastId
string
Example: lastId=urn:decentraland:ethereum:collections-v1:binance_us_collection:binance_us_hat

The result will always be ordered by the local timestamp fields but in case of timestamp collisions, you can use the lastId field to filter the result

Responses

Response samples

Content type
application/json; charset=utf-8
{}

Get Catalyst Servers

Retrieve the list of Catalyst Servers

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

Retrieve DCL Point of Interests

Retrieve the Point of Interest list of coordinates

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • "-29,55",
  • "-108,-30",
  • "144,-34",
  • "-10,58",
  • "-79,-54",
  • "111,-23",
  • "25,74",
  • "26,9",
  • "-143,-125",
  • "-25,25",
  • "-119,133",
  • "-48,-110",
  • "23,-123",
  • "38,103",
  • "82,-149",
  • "52,83",
  • "10,52",
  • "19,-120",
  • "-67,-114",
  • "22,-118",
  • "46,-52",
  • "-96,110",
  • "-108,129",
  • "-119,125",
  • "96,-30",
  • "-1,-135",
  • "-23,69",
  • "-116,-49",
  • "95,-7"
]

Denylisted user names

Retrieve list of forbidden user names. The prohibition of these names is decided through the DAO and need to be voted, the list lives in a Smart Contract and the Catalyst just consumes this information to present it to the client. In order to add a new name a new proposal needs to be created, approved and a transaction should be sent by a DAO committee member.

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • "OffensiveName1",
  • "OffensiveName2",
  • "OffensiveName3"
]

Validate signed message Deprecated

Given a signed message and it's AuthChain, validate it's authenticity. A message can be signed, for example, to prove ownership of the Entity pointers that they want to modify.

Request Body schema: application/json; charset=utf-8

The body has 3 properties. The timestamp, the signedMessage that you wish to validate and the AuthChain.
The structure of the AuthChain is described as follows:
- The first element of the chain is the original signer, and the one who will be used to validate against the blockchain
- The last element of the chain contains the EHash and a signature
- In between are ephemeral keys that can be used for signing

object

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "timestamp": "1629753096906",
  • "signedMessage": "QmfSjDEi2a43aURjbNR3KTXmBB3wWfkJb6Vdmu3vmaNW5H",
  • "authChain": [
    ]
}

Response samples

Content type
application/json
Example
{
  • "valid": true,
  • "ownerAddress": "0xa8ee490e4c4da48cc1653502c1a77479d4d818de"
}

Hot Scenes

Returns the list of scenes where there are more users with coordinates and the list of parcels that compose the scene.

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {
    }
]

Get Realms status

Returns the list of realms with details about the users in it

Responses

Response samples

Content type
application/json; charset=utf-8
[
  • {},
  • {
    },
  • {
    }
]

Get Avatars details

Returns all the Avatars details associated with the Ethereum addresses in the body

Request Body schema: application/json; charset=utf-8

The body only has the ids property representing a list of Ethereum addresses

ids
Array of strings

Responses

Request samples

Content type
application/json; charset=utf-8
{
  • "ids": [
    ]
}

Response samples

Content type
application/json
[]

Get Avatar details

Given a Ethereum address of a user, return the Avatars details associated with it.

path Parameters
id
required
string
Example: 0x22480812a9a0669783c06d359182a583bd1d9fc2

Ethereum address of the user

Responses

Response samples

Content type
application/json
{}

Get Outfits

Given a Ethereum address of a user, return the Outfits entity.

path Parameters
id
required
string
Example: 0x22480812a9a0669783c06d359182a583bd1d9fc2

Ethereum address of the user

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Returns the list of third party integrations as well as collections

Returns the list of third party integrations and collections

Responses

Response samples

Content type
application/json; charset=utf-8
{
  • "data": [
    ]
}