openapi: 3.1.0
info:
  title: Asset Bundle Registry API
  description: |
    ## Overview

    The Asset Bundle Registry is a proxy service that manages the availability of converted Unity Asset Bundles for Decentraland content. It acts as an intermediary between the Unity Client and the content network hosted in the Catalyst servers.

    ### What are Unity Asset Bundles?

    Unity Asset Bundles are optimized, pre-compiled packages of 3D assets used in Decentraland to improve performance in WebGL builds. Instead of loading raw GLTF models at runtime, scenes and wearables are converted into Asset Bundles by the Asset Bundle Converter service, which loads scene assets, re-imports GLTF models, and packages them into optimized bundles stored on a CDN.

    ### How the Registry Works

    The Asset Bundle Registry acts as an intelligent proxy between clients and the Catalyst content servers:

    1. **Content Upload**: When new content (scenes, wearables, etc.) is uploaded to a Catalyst server, it triggers the Asset Bundle Converter to process the assets.

    2. **Availability Management**: While the new content is being converted (which can take time), the registry continues to serve the **previous version** of the asset bundle for that pointer.

    3. **Seamless Transitions**: This ensures that when clients request a scene or wearable, there is always something to display in-world, preventing broken experiences during content updates.

    4. **Pointer-based Queries**: Clients query the registry by pointers (e.g., scene coordinates like "-53,71" or wearable URNs) to get the latest **available** and **ready** asset bundle, not necessarily the latest uploaded content.

    ### Key Features

    - **Always Available**: Returns the most recent successfully converted asset bundle
    - **Processing Status**: Track conversion progress of new content
    - **Multi-version Support**: Handles different Asset Bundle versions (v4, v5, etc.) based on Unity version and material changes
    - **Queue Monitoring**: Provides visibility into conversion queue status

    The registry works in conjunction with the Asset Bundle Converter service and the Catalyst content servers to provide a reliable, performant content delivery system for Decentraland.
  version: 1.0.0
  contact:
    name: Decentraland
    url: https://decentraland.org
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  x-api-id: asset-bundle-registry-api
servers:
  - url: https://asset-bundle-registry.decentraland.org
    description: Production server
  - url: /
    description: Local/relative path
security: []
tags:
  - name: Health
    description: Service health and monitoring endpoints
  - name: Entities
    description: Entity management and asset bundle queries
  - name: Profiles
    description: User profile retrieval and metadata endpoints
  - name: Queues
    description: Processing queue status and monitoring
  - name: Admin
    description: Administrative endpoints (requires bearer token authentication)
paths:
  /status:
    get:
      tags:
        - Health
      summary: Get service health status
      description: |
        Returns the health status of the Asset Bundle Registry service, including connectivity to dependent services 
        (database, cache, queues) and overall system readiness.
      operationId: getStatus
      security: []
      responses:
        '200':
          description: Service health status
          content:
            application/json:
              schema:
                type: object
                description: Health status response indicating the operational state of the service and its dependencies
                properties: &ref_11
                  status:
                    type: string
                    description: |
                      Overall health status of the service (e.g., "ok", "healthy", "degraded"). 
                      This indicates whether the service is operational and able to serve asset bundle requests.
                  timestamp:
                    type: string
                    format: date-time
                    description: ISO 8601 timestamp when the status was checked
                required: &ref_12
                  - status
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: &ref_0
                  error:
                    type: string
                    description: Error message
                  code:
                    type: string
                    description: Error code
                required: &ref_1
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /entities/active:
    post:
      tags:
        - Entities
      summary: Get active entities by pointers
      description: |
        Returns the currently active (ready-to-use) entities for the given pointers. This is the primary endpoint 
        for clients to query which asset bundles are available for display.

        **Pointers** are unique identifiers for content locations:
        - For scenes: coordinates like "-53,71" or "-100,-50"
        - For wearables: URNs like "urn:decentraland:matic:collections-v2:0x..."

        The response includes entities with their associated asset bundle content that are **ready for use**. 
        If new content is currently being processed for a pointer, this endpoint will return the previous 
        successfully converted version, ensuring clients always have something to render.
      operationId: getActiveEntities
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_13
                pointers:
                  type: array
                  items:
                    type: string
                  description: |
                    List of pointers to query for active entities. Pointers are unique identifiers for content locations:
                    - Scene coordinates (e.g., "-53,71", "0,0")
                    - Wearable URNs (e.g., "urn:decentraland:matic:collections-v2:0xabc...")
              required: &ref_14
                - pointers
      responses:
        '200':
          description: List of active entities
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: |
                    Represents a Decentraland entity (scene, wearable, etc.) with its converted asset bundle information. 
                    This is the primary data structure returned when querying for active entities.
                  properties: &ref_15
                    id:
                      type: string
                      description: Unique entity identifier (content identifier/CID from Catalyst)
                    type:
                      type: string
                      description: |
                        Entity type indicating the kind of content:
                        - `scene`: A Decentraland scene/parcel
                        - `wearable`: An avatar wearable item
                        - `profile`: A user profile
                        - `emote`: An avatar emote/animation
                    pointers:
                      type: array
                      items:
                        type: string
                      description: |
                        List of pointers where this entity is active. For scenes, these are coordinates (e.g., "-53,71"). 
                        For wearables, these are URNs identifying the item.
                    timestamp:
                      type: number
                      description: Unix timestamp (milliseconds) indicating when this entity was deployed to Catalyst
                    content:
                      type: array
                      items:
                        type: object
                        description: Represents a content file associated with an entity, including converted asset bundles
                        properties: &ref_17
                          file:
                            type: string
                            description: |
                              Relative file path of the content within the entity (e.g., "scene.json", "thumbnail.png", 
                              or converted asset bundle file names)
                          hash:
                            type: string
                            description: |
                              Content identifier (CID) hash of the file, used to retrieve the actual file from the Catalyst 
                              content server or Asset Bundle CDN
                        required: &ref_18
                          - file
                          - hash
                      description: |
                        Array of content files associated with this entity, including the converted asset bundle files. 
                        Each content item includes the file path and its hash for retrieval from the CDN.
                    metadata:
                      type: object
                      additionalProperties: true
                      description: |
                        Entity-specific metadata (structure varies by entity type):
                        - For scenes: includes display name, spawn points, parcels, etc.
                        - For wearables: includes name, description, category, rarity, etc.
                  required: &ref_16
                    - id
                    - type
                    - pointers
                    - timestamp
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /entities/status/{id}:
    get:
      tags:
        - Entities
      summary: Get entity status by ID
      description: |
        Returns the current processing status of a specific entity by its ID (typically a content identifier/CID).

        Use this endpoint to check whether an entity has been successfully converted to an asset bundle, 
        is currently being processed, or is inactive.

        **Status values:**
        - `active`: Entity has been successfully converted and is ready for use
        - `processing`: Entity is currently being converted by the Asset Bundle Converter
        - `inactive`: Entity conversion failed or the entity is no longer active
      operationId: getEntityStatus
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Entity ID (content identifier/CID)
      responses:
        '200':
          description: Entity status
          content:
            application/json:
              schema:
                type: object
                description: Represents the current processing and availability status of an entity's asset bundle conversion
                properties: &ref_4
                  entityId:
                    type: string
                    description: Unique entity identifier (content identifier/CID)
                  complete:
                    type: boolean
                    description: Whether asset bundles are fully converted for all required platforms (Windows and Mac)
                  catalyst:
                    type: string
                    enum:
                      - pending
                      - complete
                      - failed
                    description: Status of the entity in Catalyst (always 'complete' if entity exists in registry)
                  assetBundles:
                    type: object
                    description: Conversion status per platform (Windows and Mac)
                    properties: &ref_2
                      mac:
                        type: string
                        enum:
                          - pending
                          - complete
                          - failed
                        description: Conversion status for Mac platform
                      windows:
                        type: string
                        enum:
                          - pending
                          - complete
                          - failed
                        description: Conversion status for Windows platform
                    required: &ref_3
                      - mac
                      - windows
                  lods:
                    description: LOD generation status per platform.
                    type: object
                    properties: *ref_2
                    required: *ref_3
                required: &ref_5
                  - entityId
                  - complete
                  - catalyst
                  - assetBundles
        '404':
          description: Entity not found
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /entities/status:
    get:
      tags:
        - Entities
      summary: Get multiple entities status
      description: |
        Returns the processing status of multiple entities in a single request. This endpoint requires 
        authenticated access via Decentraland's signed fetch mechanism.

        Useful for batch checking the conversion status of multiple pieces of content (scenes, wearables, etc.) 
        to determine which are ready for use and which are still being processed.
      operationId: getEntitiesStatus
      security:
        - SignedFetch: []
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            type: array
            items:
              type: string
          description: Comma-separated list of entity IDs (content identifiers/CIDs)
      responses:
        '200':
          description: List of entity statuses
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Represents the current processing and availability status of an entity's asset bundle conversion
                  properties: *ref_4
                  required: *ref_5
        '401':
          description: Unauthorized - invalid signed fetch
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '403':
          description: Forbidden - invalid metadata
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /entities/versions:
    post:
      tags:
        - Entities
      summary: Get entity versions by pointers
      description: |
        Returns the version information and bundle status for entities at the given pointers.
        This endpoint is useful for checking which asset bundle versions are available for specific
        content locations and their conversion status across different platforms.

        Unlike `/entities/active` which returns full entity data, this endpoint focuses on version
        metadata and bundle availability status, making it lighter for version checking use cases.
      operationId: getEntityVersions
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_21
                pointers:
                  type: array
                  items:
                    type: string
                  description: List of pointers to query for version information
              required: &ref_22
                - pointers
      responses:
        '200':
          description: List of entity version information
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Version and bundle status information for an entity
                  properties: &ref_23
                    pointers:
                      type: array
                      items:
                        type: string
                      description: List of pointers where this entity is active
                    versions:
                      type: object
                      description: Asset bundle version information per platform
                      properties: &ref_25
                        assets:
                          type: object
                          properties:
                            windows:
                              type: object
                              description: Version details for a specific platform
                              properties: &ref_6
                                version:
                                  type: string
                                  description: Asset bundle version string (e.g., "v4", "v5")
                                buildDate:
                                  type: string
                                  description: Build date of the asset bundle
                            mac:
                              type: object
                              description: Version details for a specific platform
                              properties: *ref_6
                            webgl:
                              type: object
                              description: Version details for a specific platform
                              properties: *ref_6
                    bundles:
                      type: object
                      description: Bundle conversion status for assets and LODs across platforms
                      properties: &ref_26
                        assets:
                          type: object
                          description: Conversion status for each platform
                          properties: &ref_7
                            windows:
                              type: string
                              enum:
                                - pending
                                - complete
                                - failed
                            mac:
                              type: string
                              enum:
                                - pending
                                - complete
                                - failed
                            webgl:
                              type: string
                              enum:
                                - pending
                                - complete
                                - failed
                          required: &ref_8
                            - windows
                            - mac
                            - webgl
                        lods:
                          type: object
                          description: Conversion status for each platform
                          properties: *ref_7
                          required: *ref_8
                      required: &ref_27
                        - assets
                        - lods
                    status:
                      type: string
                      enum:
                        - complete
                        - pending
                        - failed
                        - obsolete
                        - fallback
                      description: Current status of the entity in the registry
                  required: &ref_24
                    - pointers
                    - bundles
        '400':
          description: Bad request - no pointers provided
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /queues/status:
    get:
      tags:
        - Queues
      summary: Get queue status information
      description: |
        Returns status information about the internal processing queues that handle asset bundle conversion requests.

        This endpoint provides visibility into:
        - Number of entities pending conversion
        - Number of entities currently being processed
        - Number of successfully completed conversions
        - Number of failed conversions

        Useful for monitoring system load and identifying potential bottlenecks in the asset bundle conversion pipeline.
      operationId: getQueuesStatus
      security: []
      responses:
        '200':
          description: Queue status information
          content:
            application/json:
              schema:
                type: object
                description: Status of pending conversion jobs organized by platform
                properties: &ref_19
                  windowsPendingJobs:
                    type: array
                    items:
                      type: string
                    description: List of entity IDs with pending Windows asset bundle conversions
                  macPendingJobs:
                    type: array
                    items:
                      type: string
                    description: List of entity IDs with pending Mac asset bundle conversions
                  webglPendingJobs:
                    type: array
                    items:
                      type: string
                    description: List of entity IDs with pending WebGL asset bundle conversions
                required: &ref_20
                  - windowsPendingJobs
                  - macPendingJobs
                  - webglPendingJobs
        '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
  /profiles:
    post:
      tags:
        - Profiles
      summary: Get profiles by addresses
      description: |
        Returns validated Catalyst profiles for the given Ethereum addresses. Profiles include
        avatar information, names, wearables, and snapshot URLs.

        The service maintains a multi-layer cache (memory and database) for fast profile retrieval
        and periodically validates profile ownership to ensure data freshness.

        Profile snapshots (face and body images) are returned as URLs pointing to the profile
        images CDN rather than content hashes.
      operationId: getProfiles
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_9
                ids:
                  type: array
                  items:
                    type: string
                  description: List of Ethereum addresses to fetch profiles for
              required: &ref_10
                - ids
      responses:
        '200':
          description: List of profiles
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Profile data transfer object with avatar information
                  properties: &ref_28
                    timestamp:
                      type: number
                      description: Unix timestamp (milliseconds) when the profile was deployed
                    avatars:
                      type: array
                      items:
                        type: object
                        description: Avatar configuration including appearance and wearables
                        properties: &ref_30
                          userId:
                            type: string
                            description: User's Ethereum address
                          name:
                            type: string
                            description: Display name for the avatar
                          hasClaimedName:
                            type: boolean
                            description: Whether the user has claimed a unique Decentraland name
                          description:
                            type: string
                            description: User-provided description
                          avatar:
                            type: object
                            description: Avatar appearance configuration
                            properties:
                              bodyShape:
                                type: string
                                description: Body shape URN
                              wearables:
                                type: array
                                items:
                                  type: string
                                description: List of equipped wearable URNs
                              emotes:
                                type: array
                                items:
                                  type: object
                                description: List of equipped emotes
                              snapshots:
                                type: object
                                properties:
                                  face256:
                                    type: string
                                    description: URL to face snapshot image
                                  body:
                                    type: string
                                    description: URL to body snapshot image
                              eyes:
                                type: object
                                description: Eye color configuration
                              hair:
                                type: object
                                description: Hair color configuration
                              skin:
                                type: object
                                description: Skin color configuration
                      description: List of avatar configurations for this profile
                  required: &ref_29
                    - timestamp
                    - avatars
  /profiles/metadata:
    post:
      tags:
        - Profiles
      summary: Get profile metadata by addresses
      description: |
        Returns lightweight metadata for profiles at the given Ethereum addresses.
        This endpoint returns only essential profile information (name, claimed name status,
        thumbnail URL) without full avatar details, making it suitable for displaying
        profile cards or lists.
      operationId: getProfilesMetadata
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: *ref_9
              required: *ref_10
      responses:
        '200':
          description: List of profile metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  description: Lightweight profile metadata for display purposes
                  properties: &ref_31
                    pointer:
                      type: string
                      description: Ethereum address of the profile owner
                    hasClaimedName:
                      type: boolean
                      description: Whether the user has claimed a unique Decentraland name
                    name:
                      type: string
                      description: Display name for the profile
                    thumbnailUrl:
                      type: string
                      description: URL to the profile's face thumbnail image
                  required: &ref_32
                    - pointer
                    - hasClaimedName
                    - name
                    - thumbnailUrl
  /registry:
    post:
      tags:
        - Admin
      summary: Create or update registry entries
      description: |
        Administrative endpoint for manually creating or updating registry entries.
        This endpoint fetches entity data from Catalyst and asset bundle status from
        the CDN to populate the registry.

        Use this endpoint to manually trigger registry updates for specific entities
        that may have been missed by the event-driven pipeline.
      operationId: createRegistry
      security:
        - BearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties: &ref_33
                entityIds:
                  type: array
                  items:
                    type: string
                  description: List of entity IDs (CIDs) to add or update in the registry
              required: &ref_34
                - entityIds
      responses:
        '200':
          description: Registry operation result
          content:
            application/json:
              schema:
                type: object
                description: Result of registry creation/update operation
                properties: &ref_35
                  successes:
                    type: array
                    items:
                      type: object
                    description: List of successfully processed entities
                  failures:
                    type: array
                    items:
                      type: object
                      properties:
                        entityId:
                          type: string
                          description: Entity ID that failed
                        error:
                          type: string
                          description: Error message describing the failure
                    description: List of entities that failed to process
                required: &ref_36
                  - successes
                  - failures
        '400':
          description: Bad request - no entity IDs provided
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
        '401':
          description: Unauthorized - missing or invalid bearer token
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
  /flush-cache:
    delete:
      tags:
        - Admin
      summary: Flush internal caches
      description: |
        Administrative endpoint for flushing internal job caches. This clears
        cached job status information stored in Redis/memory.


        Use this endpoint to reset cache state when troubleshooting or after
        manual database modifications.
      operationId: flushCache
      security:
        - BearerAuth: []
      responses:
        '200':
          description: Cache flush result
          content:
            application/json:
              schema:
                type: object
                description: Result of cache flush operation
                properties: &ref_37
                  ok:
                    type: boolean
                    description: Whether the operation succeeded
                  message:
                    type: string
                    description: Status message
                required: &ref_38
                  - ok
                  - message
        '401':
          description: Unauthorized - missing or invalid bearer token
          content:
            application/json:
              schema:
                type: object
                properties: *ref_0
                required: *ref_1
components:
  securitySchemes:
    SignedFetch:
      type: http
      scheme: bearer
      description: |
        Signed fetch authentication using @dcl/platform-crypto-middleware (ADR-44).
        Requires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation.
        See http://adr.decentraland.org/adr/ADR-44 for details.
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Bearer token authentication for administrative endpoints. The token must match
        the `API_ADMIN_TOKEN` environment variable configured on the server.
  schemas:
    Status:
      type: object
      description: Health status response indicating the operational state of the service and its dependencies
      properties: *ref_11
      required: *ref_12
    ActiveEntitiesRequest:
      type: object
      properties: *ref_13
      required: *ref_14
    DbEntity:
      type: object
      description: |
        Represents a Decentraland entity (scene, wearable, etc.) with its converted asset bundle information. 
        This is the primary data structure returned when querying for active entities.
      properties: *ref_15
      required: *ref_16
    Content:
      type: object
      description: Represents a content file associated with an entity, including converted asset bundles
      properties: *ref_17
      required: *ref_18
    EntityStatus:
      type: object
      description: Represents the current processing and availability status of an entity's asset bundle conversion
      properties: *ref_4
      required: *ref_5
    PlatformStatus:
      type: object
      description: Conversion status per platform (Windows and Mac)
      properties: *ref_2
      required: *ref_3
    QueueStatus:
      type: object
      description: Status of pending conversion jobs organized by platform
      properties: *ref_19
      required: *ref_20
    VersionsRequest:
      type: object
      properties: *ref_21
      required: *ref_22
    EntityVersionInfo:
      type: object
      description: Version and bundle status information for an entity
      properties: *ref_23
      required: *ref_24
    Versions:
      type: object
      description: Asset bundle version information per platform
      properties: *ref_25
    VersionInfo:
      type: object
      description: Version details for a specific platform
      properties: *ref_6
    Bundles:
      type: object
      description: Bundle conversion status for assets and LODs across platforms
      properties: *ref_26
      required: *ref_27
    BundlePlatformStatus:
      type: object
      description: Conversion status for each platform
      properties: *ref_7
      required: *ref_8
    ProfilesRequest:
      type: object
      properties: *ref_9
      required: *ref_10
    ProfileDTO:
      type: object
      description: Profile data transfer object with avatar information
      properties: *ref_28
      required: *ref_29
    Avatar:
      type: object
      description: Avatar configuration including appearance and wearables
      properties: *ref_30
    ProfileMetadataDTO:
      type: object
      description: Lightweight profile metadata for display purposes
      properties: *ref_31
      required: *ref_32
    RegistryRequest:
      type: object
      properties: *ref_33
      required: *ref_34
    RegistryResponse:
      type: object
      description: Result of registry creation/update operation
      properties: *ref_35
      required: *ref_36
    FlushCacheResponse:
      type: object
      description: Result of cache flush operation
      properties: *ref_37
      required: *ref_38
    Error:
      type: object
      properties: *ref_0
      required: *ref_1
