# Entities

Entity management and asset bundle queries

## Get active entities by pointers

> 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Asset Bundle Registry API","version":"1.0.0"},"tags":[{"name":"Entities","description":"Entity management and asset bundle queries"}],"servers":[{"url":"https://asset-bundle-registry.decentraland.org","description":"Production server"},{"url":"/","description":"Local/relative path"}],"security":[],"paths":{"/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 \nfor clients to query which asset bundles are available for display.\n\n**Pointers** are unique identifiers for content locations:\n- For scenes: coordinates like \"-53,71\" or \"-100,-50\"\n- For wearables: URNs like \"urn:decentraland:matic:collections-v2:0x...\"\n\nThe response includes entities with their associated asset bundle content that are **ready for use**. \nIf new content is currently being processed for a pointer, this endpoint will return the previous \nsuccessfully converted version, ensuring clients always have something to render.\n","operationId":"getActiveEntities","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pointers":{"type":"array","items":{"type":"string"},"description":"List of pointers to query for active entities. Pointers are unique identifiers for content locations:\n- Scene coordinates (e.g., \"-53,71\", \"0,0\")\n- Wearable URNs (e.g., \"urn:decentraland:matic:collections-v2:0xabc...\")\n"}},"required":["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. \nThis is the primary data structure returned when querying for active entities.\n","properties":{"id":{"type":"string","description":"Unique entity identifier (content identifier/CID from Catalyst)"},"type":{"type":"string","description":"Entity type indicating the kind of content:\n- `scene`: A Decentraland scene/parcel\n- `wearable`: An avatar wearable item\n- `profile`: A user profile\n- `emote`: An avatar emote/animation\n"},"pointers":{"type":"array","items":{"type":"string"},"description":"List of pointers where this entity is active. For scenes, these are coordinates (e.g., \"-53,71\"). \nFor wearables, these are URNs identifying the item.\n"},"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":{"file":{"type":"string","description":"Relative file path of the content within the entity (e.g., \"scene.json\", \"thumbnail.png\", \nor converted asset bundle file names)\n"},"hash":{"type":"string","description":"Content identifier (CID) hash of the file, used to retrieve the actual file from the Catalyst \ncontent server or Asset Bundle CDN\n"}},"required":["file","hash"]},"description":"Array of content files associated with this entity, including the converted asset bundle files. \nEach content item includes the file path and its hash for retrieval from the CDN.\n"},"metadata":{"type":"object","additionalProperties":true,"description":"Entity-specific metadata (structure varies by entity type):\n- For scenes: includes display name, spawn points, parcels, etc.\n- For wearables: includes name, description, category, rarity, etc.\n"}},"required":["id","type","pointers","timestamp"]}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"}},"required":["error"]}}}}}}}}}
```

## Get entity status by ID

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

```json
{"openapi":"3.1.0","info":{"title":"Asset Bundle Registry API","version":"1.0.0"},"tags":[{"name":"Entities","description":"Entity management and asset bundle queries"}],"servers":[{"url":"https://asset-bundle-registry.decentraland.org","description":"Production server"},{"url":"/","description":"Local/relative path"}],"security":[],"paths":{"/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).\n\nUse this endpoint to check whether an entity has been successfully converted to an asset bundle, \nis currently being processed, or is inactive.\n\n**Status values:**\n- `active`: Entity has been successfully converted and is ready for use\n- `processing`: Entity is currently being converted by the Asset Bundle Converter\n- `inactive`: Entity conversion failed or the entity is no longer active\n","operationId":"getEntityStatus","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":{"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":{"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":["mac","windows"]},"lods":{"description":"LOD generation status per platform.","type":"object","properties":{"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":["mac","windows"]}},"required":["entityId","complete","catalyst","assetBundles"]}}}},"404":{"description":"Entity not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"}},"required":["error"]}}}}}}}}}
```

## Get multiple entities status

> 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Asset Bundle Registry API","version":"1.0.0"},"tags":[{"name":"Entities","description":"Entity management and asset bundle queries"}],"servers":[{"url":"https://asset-bundle-registry.decentraland.org","description":"Production server"},{"url":"/","description":"Local/relative path"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"http","scheme":"bearer","description":"Signed fetch authentication using @dcl/platform-crypto-middleware (ADR-44).\nRequires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation.\nSee http://adr.decentraland.org/adr/ADR-44 for details.\n"}}},"paths":{"/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 \nauthenticated access via Decentraland's signed fetch mechanism.\n\nUseful for batch checking the conversion status of multiple pieces of content (scenes, wearables, etc.) \nto determine which are ready for use and which are still being processed.\n","operationId":"getEntitiesStatus","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":{"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":{"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":["mac","windows"]},"lods":{"description":"LOD generation status per platform.","type":"object","properties":{"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":["mac","windows"]}},"required":["entityId","complete","catalyst","assetBundles"]}}}}},"401":{"description":"Unauthorized - invalid signed fetch","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"}},"required":["error"]}}}},"403":{"description":"Forbidden - invalid metadata","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"}},"required":["error"]}}}}}}}}}
```

## Get entity versions by pointers

> 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.<br>

```json
{"openapi":"3.1.0","info":{"title":"Asset Bundle Registry API","version":"1.0.0"},"tags":[{"name":"Entities","description":"Entity management and asset bundle queries"}],"servers":[{"url":"https://asset-bundle-registry.decentraland.org","description":"Production server"},{"url":"/","description":"Local/relative path"}],"security":[],"paths":{"/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.\nThis endpoint is useful for checking which asset bundle versions are available for specific\ncontent locations and their conversion status across different platforms.\n\nUnlike `/entities/active` which returns full entity data, this endpoint focuses on version\nmetadata and bundle availability status, making it lighter for version checking use cases.\n","operationId":"getEntityVersions","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pointers":{"type":"array","items":{"type":"string"},"description":"List of pointers to query for version information"}},"required":["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":{"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":{"assets":{"type":"object","properties":{"windows":{"type":"object","description":"Version details for a specific platform","properties":{"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":{"version":{"type":"string","description":"Asset bundle version string (e.g., \"v4\", \"v5\")"},"buildDate":{"type":"string","description":"Build date of the asset bundle"}}},"webgl":{"type":"object","description":"Version details for a specific platform","properties":{"version":{"type":"string","description":"Asset bundle version string (e.g., \"v4\", \"v5\")"},"buildDate":{"type":"string","description":"Build date of the asset bundle"}}}}}}},"bundles":{"type":"object","description":"Bundle conversion status for assets and LODs across platforms","properties":{"assets":{"type":"object","description":"Conversion status for each platform","properties":{"windows":{"type":"string","enum":["pending","complete","failed"]},"mac":{"type":"string","enum":["pending","complete","failed"]},"webgl":{"type":"string","enum":["pending","complete","failed"]}},"required":["windows","mac","webgl"]},"lods":{"type":"object","description":"Conversion status for each platform","properties":{"windows":{"type":"string","enum":["pending","complete","failed"]},"mac":{"type":"string","enum":["pending","complete","failed"]},"webgl":{"type":"string","enum":["pending","complete","failed"]}},"required":["windows","mac","webgl"]}},"required":["assets","lods"]},"status":{"type":"string","enum":["complete","pending","failed","obsolete","fallback"],"description":"Current status of the entity in the registry"}},"required":["pointers","bundles"]}}}}},"400":{"description":"Bad request - no pointers provided","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"}},"required":["error"]}}}}}}}}}
```