openapi: 3.1.0
info:
  title: Realm Provider API
  description: |
    ## Overview
    The Realm Provider API is a central service for Decentraland that provides intelligent realm discovery, real-time scene popularity tracking, and geo-optimized content delivery. 

    This API implements the realm selection and discovery mechanisms defined in [ADR-110](https://adr.decentraland.org/adr/ADR-110), serving as the primary gateway for Decentraland clients to connect to the optimal catalyst nodes based on user location, node health, and current capacity.

    ### Key Features

    **Realm Discovery & Selection**
    - Discover all available catalyst realms with real-time user counts
    - Automatic health monitoring and filtering of catalyst nodes
    - Geo-location-based content server selection for optimal performance

    **Hot Scenes Tracking**
    - Real-time aggregation of the most popular scenes across all realms
    - Scene popularity metrics including user distribution per realm
    - Scene metadata including coordinates, parcels, and thumbnails

    **Main Realm Services**
    - Retrieve comprehensive service information for the main realm
    - Access content server, communications, BFF, and lambdas configurations
    - Support for preferred catalyst selection via query parameters

    **Health & Monitoring**
    - Service status and version information
    - Health check endpoints for integration monitoring

    ### Use Cases

    This API is designed for:
    - **Decentraland Clients**: Web and desktop clients that need to connect users to the optimal realm
    - **Analytics & Monitoring**: Tools that track metaverse activity and infrastructure health
    - **Third-Party Integrations**: Applications building on top of Decentraland infrastructure

    The API aggregates data from multiple catalyst servers distributed globally to provide a unified, intelligent view of the Decentraland metaverse infrastructure.
  version: 1.0.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-api-id: realm-provider-api
servers:
  - url: https://realm-provider.decentraland.org
    description: Production server
security: []
tags:
  - name: Health
    description: Health check and service status endpoints
  - name: Realms
    description: Realm discovery and information endpoints
  - name: Scenes
    description: Scene discovery and popularity endpoints
paths:
  /status:
    get:
      summary: Service status information
      description: Returns version, commit hash, and current timestamp for the service
      operationId: getStatus
      security: []
      tags:
        - Health
      responses:
        '200':
          description: Successful response with service status
          content:
            application/json:
              schema:
                type: object
                required:
                  - version
                  - currentTime
                  - commitHash
                properties:
                  version:
                    type: string
                    description: Current service version
                    example: 1.0.0
                  currentTime:
                    type: number
                    description: Unix timestamp in milliseconds
                    example: 1729785600000
                  commitHash:
                    type: string
                    description: Git commit hash of the deployed version
                    example: b635386a8c9d1e2f3b4c5d6e7f8g9h0i1j2k3l4m
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: &ref_0
                  error:
                    type: string
                    description: Error message
                  code:
                    type: integer
                    description: Error code
                required: &ref_1
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /realms:
    get:
      summary: List available realms
      description: |
        Returns all healthy catalyst realms plus the main realm if available.
        Each realm includes its server name, URL, and current user count.
      operationId: getRealms
      security: []
      tags:
        - Realms
      responses:
        '200':
          description: Successful response with list of realms
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Represents a catalyst realm with its connection information
                  required: &ref_2
                    - serverName
                    - url
                    - usersCount
                  properties: &ref_3
                    serverName:
                      type: string
                      description: Name of the realm server
                      example: main
                    url:
                      type: string
                      format: uri
                      description: Base URL of the realm
                      example: https://peer.decentraland.org
                    usersCount:
                      type: number
                      description: Current number of users connected to this realm
                      example: 150
              example:
                - serverName: main
                  url: https://peer.decentraland.org
                  usersCount: 150
                - serverName: catalyst-1
                  url: https://peer-ec1.decentraland.org
                  usersCount: 75
                - serverName: catalyst-2
                  url: https://peer-wc1.decentraland.org
                  usersCount: 42
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /hot-scenes:
    get:
      summary: Get hot scenes across all realms
      description: |
        Returns up to 100 scenes sorted by total user count across all realms.
        Each scene includes its ID, name, coordinates, parcels, user count, and realm distribution.
      operationId: getHotScenes
      security: []
      tags:
        - Scenes
      responses:
        '200':
          description: Successful response with list of hot scenes
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Information about a popular scene across all realms
                  required: &ref_4
                    - id
                    - baseCoords
                    - parcels
                    - usersTotalCount
                    - realms
                  properties: &ref_5
                    id:
                      type: string
                      description: Unique scene identifier
                      example: 0xScene1
                    name:
                      type: string
                      description: Display name of the scene (may be absent when scene metadata lacks a display title)
                      example: Genesis Plaza
                    baseCoords:
                      type: array
                      description: Base coordinates of the scene [x, y]
                      items:
                        type: number
                      minItems: 2
                      maxItems: 2
                      example:
                        - 0
                        - 0
                    parcels:
                      type: array
                      description: Array of parcel coordinates that make up the scene
                      items:
                        type: array
                        items:
                          type: number
                        minItems: 2
                        maxItems: 2
                      example:
                        - - 0
                          - 0
                        - - 0
                          - 1
                        - - 1
                          - 0
                        - - 1
                          - 1
                    usersTotalCount:
                      type: number
                      description: Total number of users across all realms in this scene
                      example: 87
                    realms:
                      type: array
                      description: Distribution of users across realms for this scene
                      items:
                        type: object
                        description: User count for a scene in a specific realm
                        required: &ref_6
                          - serverName
                          - usersCount
                        properties: &ref_7
                          serverName:
                            type: string
                            description: Name of the realm server
                            example: main
                          usersCount:
                            type: number
                            description: Number of users in this scene on this realm
                            example: 50
                    thumbnail:
                      type: string
                      format: uri
                      description: Optional thumbnail URL for the scene
                      example: https://content.decentraland.org/thumbnail.png
              example:
                - id: 0xScene1
                  name: Genesis Plaza
                  baseCoords:
                    - 0
                    - 0
                  parcels:
                    - - 0
                      - 0
                    - - 0
                      - 1
                    - - 1
                      - 0
                    - - 1
                      - 1
                  usersTotalCount: 87
                  realms:
                    - serverName: main
                      usersCount: 50
                    - serverName: catalyst-1
                      usersCount: 37
                  thumbnail: https://content.decentraland.org/thumbnail.png
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /main/about:
    get:
      summary: Get main realm about information
      description: |
        Returns detailed About information for the main realm, including catalyst content server details,
        comms configuration, and other realm-specific metadata.

        The response follows the About type from @dcl/catalyst-api-specs and the [ADR-110](https://adr.decentraland.org/adr/ADR-110). The content server provided to the user will be one of the closest most updated nodes based on the user location. 
      operationId: getMainAbout
      security: []
      tags:
        - Realms
      parameters:
        - name: catalyst
          in: query
          description: Preferred catalyst URL to use as the main realm. When this parameter is used, the prefer catalyst will be returned as the content server.
          required: false
          schema:
            type: string
            format: uri
            example: https://peer.decentraland.org
      responses:
        '200':
          description: Successful response with main realm about information
          content:
            application/json:
              schema:
                type: object
                description: |
                  Detailed information about the main realm, following the About type from @dcl/catalyst-api-specs.
                  Includes catalyst content server details, comms configuration, and realm metadata.
                required: &ref_8
                  - healthy
                  - content
                  - configurations
                properties: &ref_9
                  healthy:
                    type: boolean
                    description: Whether the realm is healthy and operational
                    example: true
                  acceptingUsers:
                    type: boolean
                    description: Whether the realm is currently accepting new users
                    example: true
                  content:
                    type: object
                    description: Content server information
                    properties:
                      healthy:
                        type: boolean
                        example: true
                      version:
                        type: string
                        example: 6.0.0
                      commitHash:
                        type: string
                        example: abc123def456
                      publicUrl:
                        type: string
                        format: uri
                        example: https://peer.decentraland.org/content
                  configurations:
                    type: object
                    description: Realm configuration settings
                    properties:
                      networkId:
                        type: number
                        example: 1
                      globalScenesUrn:
                        type: array
                        items:
                          type: string
                      scenesUrn:
                        type: array
                        items:
                          type: string
                  comms:
                    type: object
                    description: Communications server configuration
                    properties:
                      healthy:
                        type: boolean
                        example: true
                      protocol:
                        type: string
                        example: v3
                      adapter:
                        type: string
                        description: Communications adapter being used
                        example: ws-room-service
                  bff:
                    type: object
                    description: Backend-for-frontend service information
                    properties:
                      healthy:
                        type: boolean
                        example: true
                      userCount:
                        type: number
                        example: 150
                  lambdas:
                    type: object
                    description: Lambda functions service information
                    properties:
                      healthy:
                        type: boolean
                        example: true
                      version:
                        type: string
                        example: 5.0.0
                      publicUrl:
                        type: string
                        format: uri
                        example: https://peer.decentraland.org/lambdas
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '503':
          description: Service unavailable when no catalysts are available
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    example: No catalysts available
components:
  schemas:
    Realm:
      type: object
      description: Represents a catalyst realm with its connection information
      required: *ref_2
      properties: *ref_3
    HotSceneInfo:
      type: object
      description: Information about a popular scene across all realms
      required: *ref_4
      properties: *ref_5
    SceneRealmInfo:
      type: object
      description: User count for a scene in a specific realm
      required: *ref_6
      properties: *ref_7
    About:
      type: object
      description: |
        Detailed information about the main realm, following the About type from @dcl/catalyst-api-specs.
        Includes catalyst content server details, comms configuration, and realm metadata.
      required: *ref_8
      properties: *ref_9
    Error:
      type: object
      properties: *ref_0
      required: *ref_1
