openapi: 3.0.3
info:
  title: API Specification for the Decentraland Catalyst Server (BETA)
  version: '1.0'
  description: >-
     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:
     <br/><br/>- Archipelago
     <br/>- Content Server
     <br/>- Lambdas Service
     <br/>
     <br/>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.
  x-logo:
    url: 'https://cryptologos.cc/logos/decentraland-mana-logo.png'
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html

servers:
  - url: 'https://peer.decentraland.zone'
    description: Catalyst Development instance
  - url: 'https://peer-testing.decentraland.org'
    description: Catalyst Staging instance
  - url: 'https://peer.decentraland.org'
    description: First production Catalyst node
tags:
  - name: Global
    description: >-
      Endpoints that are about the whole catalyst or about shared services
  - name: Content Server
    description: >-
     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.
     <br/><br/>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.
     <br/><br/>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.
     <br/><br/>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.
  - name: Archipelago
    description: >-
      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.
  - name: Lambdas
    description: >-
      This service provides a set of utilities required by the Catalyst Server Clients\Consumers in order to
      retrieve or validate data.
paths:

  /about:
    $ref: 'paths/global/about.yaml'
  /stats/parcels:
    $ref: 'paths/global/stats@parcels.yaml'
  /content/audit/{entityType}/{entityId}:
    $ref: 'paths/content/content@audit@{entityType}@{entityId}.yaml'
  /content/challenge:
    $ref: paths/content/content@challenge.yaml
  /content/contents/{hashId}:
    $ref: 'paths/content/content@contents@{hashId}.yaml'
  /content/contents/{hashId}/active-entities:
    $ref: 'paths/content/content@contents@{hashId}@active-entities.yaml'
  /content/available-content:
    $ref: paths/content/content@available-content.yaml
  /content/entities:
    $ref: paths/content/content@entities.yaml
  /content/entities/active/collections/{collectionUrn}:
    $ref: paths/content/content@entities@active@collections@{collectionUrn}.yaml
  /content/entities/active:
    $ref: 'paths/content/content@entities@active.yaml'
  /content/failed-deployments:
    $ref: paths/content/content@failed-deployments.yaml
  /content/pointer-changes:
    $ref: paths/content/content@pointer-changes.yaml
  /content/snapshots:
    $ref: paths/content/content@snapshots.yaml
  /content/status:
    $ref: paths/content/content@status.yaml
  /lambdas/status:
    $ref: paths/lambdas/lambdas@status.yaml
  /lambdas/collections:
    $ref: paths/lambdas/lambdas@collections.yaml
  /lambdas/collections/contents/{urn}/thumbnail:
    $ref: 'paths/lambdas/lambdas@collections@contents@{urn}@thumbnail.yaml'
  /lambdas/collections/contents/{urn}/image:
    $ref: 'paths/lambdas/lambdas@collections@contents@{urn}@image.yaml'
  /lambdas/collections/standard/erc721/{chainId}/{contract}/{option}/{emission}:
    $ref: 'paths/lambdas/lambdas@collections@standard@erc721@{chainId}@{contract}@{option}@{emission}.yaml'
  /lambdas/users/{address}/wearables:
    $ref: 'paths/lambdas/lambdas@users@{address}@wearables.yaml'
  /lambdas/users/{address}/emotes:
    $ref: 'paths/lambdas/lambdas@users@{address}@emotes.yaml'
  /lambdas/users/{address}/names:
    $ref: 'paths/lambdas/lambdas@users@{address}@names.yaml'
  /lambdas/users/{address}/lands:
    $ref: 'paths/lambdas/lambdas@users@{address}@lands.yaml'
  /lambdas/users/{address}/third-party-wearables:
    $ref: 'paths/lambdas/lambdas@users@{address}@third-party-wearables.yaml'
  /lambdas/users/{address}/third-party-wearables/{collectionId}:
    $ref: 'paths/lambdas/lambdas@users@{address}@third-party-wearables@{collectionId}.yaml'
  /lambdas/collections/wearables:
    $ref: 'paths/lambdas/lambdas@collections@wearables.yaml'
  /lambdas/contracts/servers:
    $ref: 'paths/lambdas/lambdas@contracts@servers.yaml'
  /lambdas/contracts/pois:
    $ref: 'paths/lambdas/lambdas@contracts@pois.yaml'
  /lambdas/contracts/denylisted-names:
    $ref: 'paths/lambdas/lambdas@contracts@denylisted-names.yaml'
  /lambdas/crypto/validate-signature:
    $ref: 'paths/lambdas/lambdas@crypto@validate-signature.yaml'
  /lambdas/explore/hot-scenes:
    $ref: 'paths/lambdas/lambdas@explore@hot-scenes.yaml'
  /lambdas/explore/realms:
    $ref: 'paths/lambdas/lambdas@explore@realms.yaml'
  /lambdas/profiles:
    $ref: 'paths/lambdas/lambdas@profiles.yaml'
  /lambdas/profiles/{id}:
    $ref: 'paths/lambdas/lambdas@profiles@{id}.yaml'
  /lambdas/outfits/{id}:
    $ref: 'paths/lambdas/lambdas@outfits@{id}.yaml'
  /lambdas/third-party-integrations:
    $ref: 'paths/lambdas/lambdas@third-party-integrations.yaml'
  /comms/islands:
    $ref: 'paths/comms/comms@islands.yaml'
  /comms/islands/{islandId}:
    $ref: 'paths/comms/comms@islands@{islandId}.yaml'
  /comms/peers:
    $ref: 'paths/comms/comms@peers.yaml'