# Badges

Operations for retrieving badge definitions, details, and tier information

## List all badge definitions

> Returns a complete catalog of all badge definitions available in Decentraland.\
> \
> This endpoint returns badge metadata including:\
> \- Badge identifiers, names, and descriptions\
> \- Category classification (Explorer, Collector, Creator, Socializer, Builder)\
> \- Completion criteria and tier configurations\
> \- Asset URLs for badge images (2D and 3D)\
> \
> Note: This endpoint returns badge definitions only, not user progress. To get user-specific progress, use the \`/users/{address}/badges\` endpoint.<br>

```json
{"openapi":"3.1.0","info":{"title":"Decentraland Badges API","version":"1.0.0"},"tags":[{"name":"Badges","description":"Operations for retrieving badge definitions, details, and tier information"}],"servers":[{"url":"https://badges.decentraland.org","description":"Production environment"},{"url":"https://badges.decentraland.zone","description":"Development environment"}],"security":[],"paths":{"/badges":{"get":{"tags":["Badges"],"summary":"List all badge definitions","description":"Returns a complete catalog of all badge definitions available in Decentraland.\n\nThis endpoint returns badge metadata including:\n- Badge identifiers, names, and descriptions\n- Category classification (Explorer, Collector, Creator, Socializer, Builder)\n- Completion criteria and tier configurations\n- Asset URLs for badge images (2D and 3D)\n\nNote: This endpoint returns badge definitions only, not user progress. To get user-specific progress, use the `/users/{address}/badges` endpoint.\n","operationId":"getBadges","responses":{"200":{"description":"Successfully retrieved all badge definitions","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","description":"Complete badge definition including metadata, criteria, tiers, and assets","properties":{"id":{"type":"string","description":"Unique badge identifier"},"name":{"type":"string","description":"Human-readable badge name"},"description":{"type":"string","description":"Detailed description of the badge and how to earn it"},"category":{"type":"string","enum":["Explorer","Collector","Creator","Socializer","Builder"],"description":"Category classification for the badge"},"criteria":{"type":"object","description":"Badge completion criteria (for non-tiered badges)","properties":{"steps":{"type":"integer","description":"Number of steps/actions required to complete the badge"}},"additionalProperties":true},"tiers":{"type":"array","description":"Progressive tier definitions (only present for tiered badges)","items":{"type":"object","description":"A single tier within a progressive badge system","properties":{"tierId":{"type":"string","description":"Unique tier identifier (format: badgeName-tierLevel)"},"tierName":{"type":"string","description":"Human-readable tier name","enum":["Starter","Bronze","Silver","Gold","Platinum","Diamond"]},"description":{"type":"string","description":"Specific requirements to achieve this tier"},"criteria":{"type":"object","description":"Tier completion criteria","properties":{"steps":{"type":"integer","description":"Number of steps/actions required to achieve this tier"}},"additionalProperties":true},"assets":{"type":"object","description":"Asset URLs for badge imagery in different formats","properties":{"2d":{"type":"object","description":"2D badge assets","properties":{"normal":{"type":"string","description":"Standard 2D badge image URL"}},"required":["normal"]},"3d":{"type":"object","description":"3D badge assets for rendering in-world","properties":{"normal":{"type":"string","description":"3D model file URL"},"hrm":{"type":"string","description":"Height/roughness/metallic texture map URL"},"basecolor":{"type":"string","description":"Base color texture map URL"}},"required":["normal","hrm","basecolor"]}}}},"required":["tierId","tierName","description"]}},"assets":{"type":"object","description":"Asset URLs for badge imagery in different formats","properties":{"2d":{"type":"object","description":"2D badge assets","properties":{"normal":{"type":"string","description":"Standard 2D badge image URL"}},"required":["normal"]},"3d":{"type":"object","description":"3D badge assets for rendering in-world","properties":{"normal":{"type":"string","description":"3D model file URL"},"hrm":{"type":"string","description":"Height/roughness/metallic texture map URL"},"basecolor":{"type":"string","description":"Base color texture map URL"}},"required":["normal","hrm","basecolor"]}}}},"required":["id","name","description","category"]}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","description":"Error response object","properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","description":"Error response object","properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"}},"required":["error"]}}}}}}}}}
```

## Get specific badge details

> Returns detailed information about a specific badge by its ID.\
> \
> This endpoint provides the complete badge definition including:\
> \- Badge name, description, and category\
> \- Completion criteria (number of steps required)\
> \- Tier definitions (if the badge has progressive tiers)\
> \- 2D and 3D asset URLs for rendering the badge\
> \
> Example badge IDs: \`dclcitizen\`, \`traveler\`, \`fashionista\`, \`emote\_creator\`<br>

```json
{"openapi":"3.1.0","info":{"title":"Decentraland Badges API","version":"1.0.0"},"tags":[{"name":"Badges","description":"Operations for retrieving badge definitions, details, and tier information"}],"servers":[{"url":"https://badges.decentraland.org","description":"Production environment"},{"url":"https://badges.decentraland.zone","description":"Development environment"}],"security":[],"paths":{"/badges/{id}":{"get":{"tags":["Badges"],"summary":"Get specific badge details","description":"Returns detailed information about a specific badge by its ID.\n\nThis endpoint provides the complete badge definition including:\n- Badge name, description, and category\n- Completion criteria (number of steps required)\n- Tier definitions (if the badge has progressive tiers)\n- 2D and 3D asset URLs for rendering the badge\n\nExample badge IDs: `dclcitizen`, `traveler`, `fashionista`, `emote_creator`\n","operationId":"getBadgeDetails","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Unique badge identifier (e.g., 'dclcitizen', 'traveler', 'fashionista')"}],"responses":{"200":{"description":"Successfully retrieved badge details","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"badge":{"type":"object","description":"Complete badge definition including metadata, criteria, tiers, and assets","properties":{"id":{"type":"string","description":"Unique badge identifier"},"name":{"type":"string","description":"Human-readable badge name"},"description":{"type":"string","description":"Detailed description of the badge and how to earn it"},"category":{"type":"string","enum":["Explorer","Collector","Creator","Socializer","Builder"],"description":"Category classification for the badge"},"criteria":{"type":"object","description":"Badge completion criteria (for non-tiered badges)","properties":{"steps":{"type":"integer","description":"Number of steps/actions required to complete the badge"}},"additionalProperties":true},"tiers":{"type":"array","description":"Progressive tier definitions (only present for tiered badges)","items":{"type":"object","description":"A single tier within a progressive badge system","properties":{"tierId":{"type":"string","description":"Unique tier identifier (format: badgeName-tierLevel)"},"tierName":{"type":"string","description":"Human-readable tier name","enum":["Starter","Bronze","Silver","Gold","Platinum","Diamond"]},"description":{"type":"string","description":"Specific requirements to achieve this tier"},"criteria":{"type":"object","description":"Tier completion criteria","properties":{"steps":{"type":"integer","description":"Number of steps/actions required to achieve this tier"}},"additionalProperties":true},"assets":{"type":"object","description":"Asset URLs for badge imagery in different formats","properties":{"2d":{"type":"object","description":"2D badge assets","properties":{"normal":{"type":"string","description":"Standard 2D badge image URL"}},"required":["normal"]},"3d":{"type":"object","description":"3D badge assets for rendering in-world","properties":{"normal":{"type":"string","description":"3D model file URL"},"hrm":{"type":"string","description":"Height/roughness/metallic texture map URL"},"basecolor":{"type":"string","description":"Base color texture map URL"}},"required":["normal","hrm","basecolor"]}}}},"required":["tierId","tierName","description"]}},"assets":{"type":"object","description":"Asset URLs for badge imagery in different formats","properties":{"2d":{"type":"object","description":"2D badge assets","properties":{"normal":{"type":"string","description":"Standard 2D badge image URL"}},"required":["normal"]},"3d":{"type":"object","description":"3D badge assets for rendering in-world","properties":{"normal":{"type":"string","description":"3D model file URL"},"hrm":{"type":"string","description":"Height/roughness/metallic texture map URL"},"basecolor":{"type":"string","description":"Base color texture map URL"}},"required":["normal","hrm","basecolor"]}}}},"required":["id","name","description","category"]}}}}}}}},"404":{"description":"Badge with the specified ID was not found","content":{"application/json":{"schema":{"type":"object","description":"Error response object","properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"}},"required":["error"]}}}}}}}}}
```

## Get badge tier progression

> Returns the tier progression system for a specific badge.\
> \
> Many badges in Decentraland have progressive tiers that users can unlock by achieving higher milestones:\
> \- \*\*Starter\*\*: Initial tier, easiest to achieve\
> \- \*\*Bronze\*\*: Second tier, moderate difficulty\
> \- \*\*Silver\*\*: Third tier, increasing challenge\
> \- \*\*Gold\*\*: Fourth tier, significant achievement\
> \- \*\*Platinum\*\*: Fifth tier, major accomplishment\
> \- \*\*Diamond\*\*: Sixth tier, highest achievement\
> \
> Each tier has its own:\
> \- Criteria/requirements (e.g., "Visit 50 scenes" for Bronze, "Visit 250 scenes" for Silver)\
> \- Unique badge assets and imagery\
> \- Tier-specific descriptions\
> \
> Badges without tiers return an empty array.<br>

```json
{"openapi":"3.1.0","info":{"title":"Decentraland Badges API","version":"1.0.0"},"tags":[{"name":"Badges","description":"Operations for retrieving badge definitions, details, and tier information"}],"servers":[{"url":"https://badges.decentraland.org","description":"Production environment"},{"url":"https://badges.decentraland.zone","description":"Development environment"}],"security":[],"paths":{"/badges/{id}/tiers":{"get":{"tags":["Badges"],"summary":"Get badge tier progression","description":"Returns the tier progression system for a specific badge.\n\nMany badges in Decentraland have progressive tiers that users can unlock by achieving higher milestones:\n- **Starter**: Initial tier, easiest to achieve\n- **Bronze**: Second tier, moderate difficulty\n- **Silver**: Third tier, increasing challenge\n- **Gold**: Fourth tier, significant achievement\n- **Platinum**: Fifth tier, major accomplishment\n- **Diamond**: Sixth tier, highest achievement\n\nEach tier has its own:\n- Criteria/requirements (e.g., \"Visit 50 scenes\" for Bronze, \"Visit 250 scenes\" for Silver)\n- Unique badge assets and imagery\n- Tier-specific descriptions\n\nBadges without tiers return an empty array.\n","operationId":"getBadgeTiers","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Badge identifier"}],"responses":{"200":{"description":"Successfully retrieved badge tiers (may be empty for non-tiered badges)","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"tiers":{"type":"array","items":{"type":"object","description":"A single tier within a progressive badge system","properties":{"tierId":{"type":"string","description":"Unique tier identifier (format: badgeName-tierLevel)"},"tierName":{"type":"string","description":"Human-readable tier name","enum":["Starter","Bronze","Silver","Gold","Platinum","Diamond"]},"description":{"type":"string","description":"Specific requirements to achieve this tier"},"criteria":{"type":"object","description":"Tier completion criteria","properties":{"steps":{"type":"integer","description":"Number of steps/actions required to achieve this tier"}},"additionalProperties":true},"assets":{"type":"object","description":"Asset URLs for badge imagery in different formats","properties":{"2d":{"type":"object","description":"2D badge assets","properties":{"normal":{"type":"string","description":"Standard 2D badge image URL"}},"required":["normal"]},"3d":{"type":"object","description":"3D badge assets for rendering in-world","properties":{"normal":{"type":"string","description":"3D model file URL"},"hrm":{"type":"string","description":"Height/roughness/metallic texture map URL"},"basecolor":{"type":"string","description":"Base color texture map URL"}},"required":["normal","hrm","basecolor"]}}}},"required":["tierId","tierName","description"]}}}}}}}}},"404":{"description":"Badge with the specified ID was not found","content":{"application/json":{"schema":{"type":"object","description":"Error response object","properties":{"error":{"type":"string","description":"Human-readable error message"},"code":{"type":"string","description":"Machine-readable error code"}},"required":["error"]}}}}}}}}}
```