# Picks

Manage picks within favorites lists

## Get statistics for a specific item

> Retrieves pick statistics for a specific marketplace item.\
> \
> Returns:\
> \- Total number of times the item has been picked (added to lists)\
> \- Number of different lists containing this item\
> \- Popularity metrics\
> \
> Authentication is optional but may provide additional user-specific data.<br>

```json
{"openapi":"3.1.0","info":{"title":"Decentraland Marketplace Server API","version":"1.0.0"},"tags":[{"name":"Picks","description":"Manage picks within favorites lists"}],"servers":[{"url":"https://marketplace-api.decentraland.org","description":"Production server"},{"url":"https://marketplace-api.decentraland.zone","description":"Development server"}],"security":[{"SignedFetch":[]},{}],"components":{"securitySchemes":{"SignedFetch":{"type":"http","scheme":"bearer","description":"Signed fetch authentication using decentraland-crypto-middleware with metadata validation (ADR-44l). \nRequires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation. \nSee http://adr.decentraland.org/adr/ADR-44l for details.\n"}}},"paths":{"/v1/picks/{itemId}/stats":{"get":{"tags":["Picks"],"summary":"Get statistics for a specific item","description":"Retrieves pick statistics for a specific marketplace item.\n\nReturns:\n- Total number of times the item has been picked (added to lists)\n- Number of different lists containing this item\n- Popularity metrics\n\nAuthentication is optional but may provide additional user-specific data.\n","operationId":"getPickStats","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of the marketplace item"}],"responses":{"200":{"description":"Pick statistics","content":{"application/json":{"schema":{"type":"object","properties":{"itemId":{"type":"string","description":"Item ID"},"pickCount":{"type":"number","description":"Number of picks"},"listsCount":{"type":"number","description":"Number of lists containing this item"}},"required":["itemId","pickCount","listsCount"]}}}}}}}}}
```

## Get global pick statistics

> Retrieves aggregated statistics across all picks in the marketplace.\
> \
> Returns:\
> \- Total number of picks across all lists\
> \- Total number of unique items that have been picked\
> \- Total number of active lists\
> \
> Use this endpoint for global marketplace analytics and engagement metrics.<br>

```json
{"openapi":"3.1.0","info":{"title":"Decentraland Marketplace Server API","version":"1.0.0"},"tags":[{"name":"Picks","description":"Manage picks within favorites lists"}],"servers":[{"url":"https://marketplace-api.decentraland.org","description":"Production server"},{"url":"https://marketplace-api.decentraland.zone","description":"Development server"}],"security":[],"paths":{"/v1/picks/stats":{"get":{"tags":["Picks"],"summary":"Get global pick statistics","description":"Retrieves aggregated statistics across all picks in the marketplace.\n\nReturns:\n- Total number of picks across all lists\n- Total number of unique items that have been picked\n- Total number of active lists\n\nUse this endpoint for global marketplace analytics and engagement metrics.\n","operationId":"getAllPicksStats","responses":{"200":{"description":"All picks statistics","content":{"application/json":{"schema":{"type":"object","properties":{"totalPicks":{"type":"number","description":"Total number of picks"},"totalItems":{"type":"number","description":"Total number of items picked"},"totalLists":{"type":"number","description":"Total number of lists"}},"required":["totalPicks","totalItems","totalLists"]}}}}}}}}}
```

## Get all picks for a specific item

> Retrieves all pick instances for a specific marketplace item.\
> Shows which lists contain this item and associated pick metadata.\
> \
> Authentication is optional but may provide access to private lists if the user has permissions.<br>

```json
{"openapi":"3.1.0","info":{"title":"Decentraland Marketplace Server API","version":"1.0.0"},"tags":[{"name":"Picks","description":"Manage picks within favorites lists"}],"servers":[{"url":"https://marketplace-api.decentraland.org","description":"Production server"},{"url":"https://marketplace-api.decentraland.zone","description":"Development server"}],"security":[{"SignedFetch":[]},{}],"components":{"securitySchemes":{"SignedFetch":{"type":"http","scheme":"bearer","description":"Signed fetch authentication using decentraland-crypto-middleware with metadata validation (ADR-44l). \nRequires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation. \nSee http://adr.decentraland.org/adr/ADR-44l for details.\n"}}},"paths":{"/v1/picks/{itemId}":{"get":{"tags":["Picks"],"summary":"Get all picks for a specific item","description":"Retrieves all pick instances for a specific marketplace item.\nShows which lists contain this item and associated pick metadata.\n\nAuthentication is optional but may provide access to private lists if the user has permissions.\n","operationId":"getPicksForItem","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of the marketplace item"}],"responses":{"200":{"description":"Item picks","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Pick ID"},"itemId":{"type":"string","description":"Item ID"},"listId":{"type":"string","description":"List ID"},"user":{"type":"string","description":"User address"},"createdAt":{"type":"string","format":"date-time","description":"Pick creation timestamp"}},"required":["id","itemId","listId","user"]}}}}}}}}}}
```

## Bulk pick/unpick operation

> Adds or removes an item from multiple favorites lists in a single operation.\
> \
> \*\*Authentication Required\*\*: User must be authenticated and authorized.\
> \
> Use cases:\
> \- Add an item to multiple lists at once\
> \- Remove an item from multiple lists at once\
> \
> This is more efficient than making individual pick/unpick requests when managing multiple lists.<br>

```json
{"openapi":"3.1.0","info":{"title":"Decentraland Marketplace Server API","version":"1.0.0"},"tags":[{"name":"Picks","description":"Manage picks within favorites lists"}],"servers":[{"url":"https://marketplace-api.decentraland.org","description":"Production server"},{"url":"https://marketplace-api.decentraland.zone","description":"Development server"}],"security":[{"SignedFetch":[]}],"components":{"securitySchemes":{"SignedFetch":{"type":"http","scheme":"bearer","description":"Signed fetch authentication using decentraland-crypto-middleware with metadata validation (ADR-44l). \nRequires auth chain headers (x-identity, x-signature, x-timestamp) for signature validation. \nSee http://adr.decentraland.org/adr/ADR-44l for details.\n"}}},"paths":{"/v1/picks/{itemId}":{"post":{"tags":["Picks"],"summary":"Bulk pick/unpick operation","description":"Adds or removes an item from multiple favorites lists in a single operation.\n\n**Authentication Required**: User must be authenticated and authorized.\n\nUse cases:\n- Add an item to multiple lists at once\n- Remove an item from multiple lists at once\n\nThis is more efficient than making individual pick/unpick requests when managing multiple lists.\n","operationId":"bulkPickUnpick","parameters":[{"name":"itemId","in":"path","required":true,"schema":{"type":"string"},"description":"Unique identifier of the marketplace item to pick/unpick"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["pick","unpick"],"description":"Action to perform"},"listIds":{"type":"array","items":{"type":"string"},"description":"List of list IDs"}},"required":["action","listIds"]}}}},"responses":{"200":{"description":"Bulk operation completed","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Operation success status"},"processed":{"type":"number","description":"Number of items processed"}},"required":["success","processed"]}}}},"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"]}}}}}}}}}
```