> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/apis/apis/builder-server/items.md).

# Items

Wearable and emote item management

## Get all items

> Returns all items (committee members only)

```json
{"openapi":"3.0.3","info":{"title":"Builder Server API","version":"2.10.0"},"tags":[{"name":"Items","description":"Wearable and emote item management"}],"servers":[{"url":"https://builder-api.decentraland.org/v1","description":"Production environment","variables":{}},{"url":"https://builder-api.decentraland.zone/v1","description":"Development environment","variables":{}}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"X-Identity-Auth-Chain-*","description":"Signed fetch authentication using Decentraland's ADR-44 specification.\nMultiple headers are used to provide the authentication chain.\n"}}},"paths":{"/items":{"get":{"operationId":"getItems","tags":["Items"],"summary":"Get all items","description":"Returns all items (committee members only)","responses":{"200":{"description":"List of items","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"urn":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"thumbnail":{"type":"string"},"video":{"type":"string"},"eth_address":{"type":"string"},"collection_id":{"type":"string","format":"uuid"},"blockchain_item_id":{"type":"string"},"price":{"type":"string"},"beneficiary":{"type":"string"},"rarity":{"type":"string","enum":["common","uncommon","rare","epic","legendary","mythic","unique"]},"type":{"type":"string","enum":["wearable","emote"]},"data":{"type":"object"},"metrics":{"type":"object"},"utility":{"type":"string"},"contents":{"type":"object","additionalProperties":{"type":"string"}},"mappings":{"type":"object"},"is_published":{"type":"boolean"},"is_approved":{"type":"boolean"},"in_catalyst":{"type":"boolean"},"total_supply":{"type":"integer"},"content_hash":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},{"type":"object","properties":{"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"page":{"type":"integer"},"pages":{"type":"integer"},"limit":{"type":"integer"}}}]}}}}}},"401":{"description":"Unauthorized - authentication required or insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}
```

## Get items by address

> Returns items for a specific address

```json
{"openapi":"3.0.3","info":{"title":"Builder Server API","version":"2.10.0"},"tags":[{"name":"Items","description":"Wearable and emote item management"}],"servers":[{"url":"https://builder-api.decentraland.org/v1","description":"Production environment","variables":{}},{"url":"https://builder-api.decentraland.zone/v1","description":"Development environment","variables":{}}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"X-Identity-Auth-Chain-*","description":"Signed fetch authentication using Decentraland's ADR-44 specification.\nMultiple headers are used to provide the authentication chain.\n"}}},"paths":{"/{address}/items":{"get":{"operationId":"getItemsByAddress","tags":["Items"],"summary":"Get items by address","description":"Returns items for a specific address","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}},{"name":"collectionId","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of items per page"}],"responses":{"200":{"description":"List of items","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"urn":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"thumbnail":{"type":"string"},"video":{"type":"string"},"eth_address":{"type":"string"},"collection_id":{"type":"string","format":"uuid"},"blockchain_item_id":{"type":"string"},"price":{"type":"string"},"beneficiary":{"type":"string"},"rarity":{"type":"string","enum":["common","uncommon","rare","epic","legendary","mythic","unique"]},"type":{"type":"string","enum":["wearable","emote"]},"data":{"type":"object"},"metrics":{"type":"object"},"utility":{"type":"string"},"contents":{"type":"object","additionalProperties":{"type":"string"}},"mappings":{"type":"object"},"is_published":{"type":"boolean"},"is_approved":{"type":"boolean"},"in_catalyst":{"type":"boolean"},"total_supply":{"type":"integer"},"content_hash":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},{"type":"object","properties":{"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"page":{"type":"integer"},"pages":{"type":"integer"},"limit":{"type":"integer"}}}]}}}}}},"401":{"description":"Unauthorized - authentication required or insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}
```

## Get an item

> Returns an item by ID

```json
{"openapi":"3.0.3","info":{"title":"Builder Server API","version":"2.10.0"},"tags":[{"name":"Items","description":"Wearable and emote item management"}],"servers":[{"url":"https://builder-api.decentraland.org/v1","description":"Production environment","variables":{}},{"url":"https://builder-api.decentraland.zone/v1","description":"Development environment","variables":{}}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"X-Identity-Auth-Chain-*","description":"Signed fetch authentication using Decentraland's ADR-44 specification.\nMultiple headers are used to provide the authentication chain.\n"}}},"paths":{"/items/{id}":{"get":{"operationId":"getItem","tags":["Items"],"summary":"Get an item","description":"Returns an item by ID","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Item UUID"}],"responses":{"200":{"description":"Item details","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"urn":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"thumbnail":{"type":"string"},"video":{"type":"string"},"eth_address":{"type":"string"},"collection_id":{"type":"string","format":"uuid"},"blockchain_item_id":{"type":"string"},"price":{"type":"string"},"beneficiary":{"type":"string"},"rarity":{"type":"string","enum":["common","uncommon","rare","epic","legendary","mythic","unique"]},"type":{"type":"string","enum":["wearable","emote"]},"data":{"type":"object"},"metrics":{"type":"object"},"utility":{"type":"string"},"contents":{"type":"object","additionalProperties":{"type":"string"}},"mappings":{"type":"object"},"is_published":{"type":"boolean"},"is_approved":{"type":"boolean"},"in_catalyst":{"type":"boolean"},"total_supply":{"type":"integer"},"content_hash":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}}}}}},"401":{"description":"Unauthorized - authentication required or insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}
```

## Create or update an item

> Creates a new item or updates an existing one (by ID or URN)

```json
{"openapi":"3.0.3","info":{"title":"Builder Server API","version":"2.10.0"},"tags":[{"name":"Items","description":"Wearable and emote item management"}],"servers":[{"url":"https://builder-api.decentraland.org/v1","description":"Production environment","variables":{}},{"url":"https://builder-api.decentraland.zone/v1","description":"Development environment","variables":{}}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"X-Identity-Auth-Chain-*","description":"Signed fetch authentication using Decentraland's ADR-44 specification.\nMultiple headers are used to provide the authentication chain.\n"}}},"paths":{"/items/{id}":{"put":{"operationId":"upsertItem","tags":["Items"],"summary":"Create or update an item","description":"Creates a new item or updates an existing one (by ID or URN)","parameters":[{"name":"id","description":"Item UUID or URN","in":"path","required":true,"schema":{"oneOf":[{"type":"string","format":"uuid"},{"type":"string","pattern":"^(urn:decentraland:(mainnet|goerli|sepolia|matic|mumbai|amoy):collections-thirdparty:[^:|\\\\s]+):([^:|\\\\s]+):([^:|\\\\s]+)$"}]}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","name","description","rarity","type","data","contents"],"properties":{"id":{"type":"string","format":"uuid"},"urn":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"collection_id":{"type":"string","format":"uuid"},"rarity":{"type":"string"},"type":{"type":"string","enum":["wearable","emote"]},"data":{"type":"object"},"contents":{"type":"object"},"utility":{"type":"string"},"mappings":{"type":"object"}}}}}},"responses":{"200":{"description":"Item created/updated successfully"},"400":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"401":{"description":"Unauthorized - authentication required or insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"409":{"description":"Conflict - resource already exists or is in an invalid state","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"423":{"description":"Resource is locked and cannot be modified","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}
```

## Delete an item

> Deletes an item

```json
{"openapi":"3.0.3","info":{"title":"Builder Server API","version":"2.10.0"},"tags":[{"name":"Items","description":"Wearable and emote item management"}],"servers":[{"url":"https://builder-api.decentraland.org/v1","description":"Production environment","variables":{}},{"url":"https://builder-api.decentraland.zone/v1","description":"Development environment","variables":{}}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"X-Identity-Auth-Chain-*","description":"Signed fetch authentication using Decentraland's ADR-44 specification.\nMultiple headers are used to provide the authentication chain.\n"}}},"paths":{"/items/{id}":{"delete":{"operationId":"deleteItem","tags":["Items"],"summary":"Delete an item","description":"Deletes an item","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Item UUID"}],"responses":{"200":{"description":"Item deleted successfully"},"401":{"description":"Unauthorized - authentication required or insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"409":{"description":"Conflict - resource already exists or is in an invalid state","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"423":{"description":"Resource is locked and cannot be modified","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}
```

## Get collection items

> Returns items for a specific collection

```json
{"openapi":"3.0.3","info":{"title":"Builder Server API","version":"2.10.0"},"tags":[{"name":"Items","description":"Wearable and emote item management"}],"servers":[{"url":"https://builder-api.decentraland.org/v1","description":"Production environment","variables":{}},{"url":"https://builder-api.decentraland.zone/v1","description":"Development environment","variables":{}}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"X-Identity-Auth-Chain-*","description":"Signed fetch authentication using Decentraland's ADR-44 specification.\nMultiple headers are used to provide the authentication chain.\n"}}},"paths":{"/collections/{id}/items":{"get":{"operationId":"getCollectionItems","tags":["Items"],"summary":"Get collection items","description":"Returns items for a specific collection","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Collection UUID"},{"name":"status","in":"query","schema":{"type":"string","enum":["pending","approved","rejected","to_review","under_review"]}},{"name":"synced","in":"query","schema":{"type":"string"}},{"name":"mappingStatus","in":"query","schema":{"type":"string","enum":["missing_mapping","unpublished_mapping"]}},{"name":"name","in":"query","schema":{"type":"string"}},{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number for pagination"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Number of items per page"}],"responses":{"200":{"description":"List of items","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"oneOf":[{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"urn":{"type":"string"},"name":{"type":"string"},"description":{"type":"string"},"thumbnail":{"type":"string"},"video":{"type":"string"},"eth_address":{"type":"string"},"collection_id":{"type":"string","format":"uuid"},"blockchain_item_id":{"type":"string"},"price":{"type":"string"},"beneficiary":{"type":"string"},"rarity":{"type":"string","enum":["common","uncommon","rare","epic","legendary","mythic","unique"]},"type":{"type":"string","enum":["wearable","emote"]},"data":{"type":"object"},"metrics":{"type":"object"},"utility":{"type":"string"},"contents":{"type":"object","additionalProperties":{"type":"string"}},"mappings":{"type":"object"},"is_published":{"type":"boolean"},"is_approved":{"type":"boolean"},"in_catalyst":{"type":"boolean"},"total_supply":{"type":"integer"},"content_hash":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}}},{"type":"object","properties":{"results":{"type":"array","items":{"type":"object"}},"total":{"type":"integer"},"page":{"type":"integer"},"pages":{"type":"integer"},"limit":{"type":"integer"}}}]}}}}}},"400":{"description":"Bad request - invalid input","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"401":{"description":"Unauthorized - authentication required or insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}
```

## Upload item files

> Uploads content files for an item

```json
{"openapi":"3.0.3","info":{"title":"Builder Server API","version":"2.10.0"},"tags":[{"name":"Items","description":"Wearable and emote item management"}],"servers":[{"url":"https://builder-api.decentraland.org/v1","description":"Production environment","variables":{}},{"url":"https://builder-api.decentraland.zone/v1","description":"Development environment","variables":{}}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"X-Identity-Auth-Chain-*","description":"Signed fetch authentication using Decentraland's ADR-44 specification.\nMultiple headers are used to provide the authentication chain.\n"}}},"paths":{"/items/{id}/files":{"post":{"operationId":"uploadItemFiles","tags":["Items"],"summary":"Upload item files","description":"Uploads content files for an item","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Item UUID"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Files uploaded successfully"},"401":{"description":"Unauthorized - authentication required or insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}
```

## Upload item video

> Uploads a video file for an item (max 250MB)

```json
{"openapi":"3.0.3","info":{"title":"Builder Server API","version":"2.10.0"},"tags":[{"name":"Items","description":"Wearable and emote item management"}],"servers":[{"url":"https://builder-api.decentraland.org/v1","description":"Production environment","variables":{}},{"url":"https://builder-api.decentraland.zone/v1","description":"Development environment","variables":{}}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"apiKey","in":"header","name":"X-Identity-Auth-Chain-*","description":"Signed fetch authentication using Decentraland's ADR-44 specification.\nMultiple headers are used to provide the authentication chain.\n"}}},"paths":{"/items/{id}/videos":{"post":{"operationId":"uploadItemVideo","tags":["Items"],"summary":"Upload item video","description":"Uploads a video file for an item (max 250MB)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Item UUID"}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Video uploaded successfully"},"401":{"description":"Unauthorized - authentication required or insufficient permissions","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}
```

## Get item contents

> Returns item contents by contract address and item ID

```json
{"openapi":"3.0.3","info":{"title":"Builder Server API","version":"2.10.0"},"tags":[{"name":"Items","description":"Wearable and emote item management"}],"servers":[{"url":"https://builder-api.decentraland.org/v1","description":"Production environment","variables":{}},{"url":"https://builder-api.decentraland.zone/v1","description":"Development environment","variables":{}}],"security":[],"paths":{"/items/{collectionAddress}/{itemId}/contents":{"get":{"operationId":"getItemContents","tags":["Items"],"summary":"Get item contents","description":"Returns item contents by contract address and item ID","parameters":[{"name":"collectionAddress","in":"path","required":true,"schema":{"type":"string"}},{"name":"itemId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Item contents","content":{"application/json":{"schema":{"type":"object","additionalProperties":{"type":"string"}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}
```

## Get item utility

> Returns the utility field for a published item

```json
{"openapi":"3.0.3","info":{"title":"Builder Server API","version":"2.10.0"},"tags":[{"name":"Items","description":"Wearable and emote item management"}],"servers":[{"url":"https://builder-api.decentraland.org/v1","description":"Production environment","variables":{}},{"url":"https://builder-api.decentraland.zone/v1","description":"Development environment","variables":{}}],"security":[],"paths":{"/published-collections/{address}/items/{id}/utility":{"get":{"operationId":"getItemUtility","tags":["Items"],"summary":"Get item utility","description":"Returns the utility field for a published item","parameters":[{"name":"address","in":"path","required":true,"schema":{"type":"string"}},{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Item utility","content":{"application/json":{"schema":{"type":"object","properties":{"utility":{"type":"string","nullable":true}}}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"error":{"type":"string"},"data":{"type":"object"}}}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.decentraland.org/apis/apis/builder-server/items.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.