openapi: 3.1.0
info:
  title: Decentraland Badges API
  description: |
    ## Overview
    The Badges API provides endpoints for managing and tracking achievement badges in the Decentraland ecosystem and works with the [Badges Processor](https://github.com/decentraland/badges/tree/main/processor) service, in charge of processing events and granting badges. 

    Badges are achievement awards that users can earn by completing specific actions in Decentraland, such as:
    - Exploring scenes and locations (Explorer category)
    - Collecting and equipping wearables and emotes (Collector category)
    - Creating content like wearables and emotes (Creator category)
    - Social interactions and event attendance (Socializer category)
    - Building and deploying scenes (Builder category)

    Many badges support progressive tiers (Starter, Bronze, Silver, Gold, Platinum, Diamond) that unlock as users achieve higher milestones.

    This API allows you to:
    - Retrieve badge definitions and metadata
    - Track user progress toward badge completion
    - Query badge categories and tier requirements
    - Monitor user achievements across all badges
  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: badges-api
servers:
  - url: https://badges.decentraland.org
    description: Production environment
  - url: https://badges.decentraland.zone
    description: Development environment
security: []
tags:
  - name: Badges
    description: Operations for retrieving badge definitions, details, and tier information
  - name: User Progress
    description: Operations for tracking user badge achievements and progress
  - name: Categories
    description: Operations for badge category management
  - name: Health
    description: Service health and status monitoring
paths:
  /badges:
    get:
      tags:
        - Badges
      summary: List all badge definitions
      description: |
        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.
      operationId: getBadges
      security: []
      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: &ref_3
                        id:
                          type: string
                          description: Unique badge identifier
                          example: traveler
                        name:
                          type: string
                          description: Human-readable badge name
                          example: Traveler
                        description:
                          type: string
                          description: Detailed description of the badge and how to earn it
                          example: Explore Genesis City scenes for at least 1 minute each. Progress through tiers from 1 scene (Starter) to 10,000 scenes (Diamond).
                        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
                              example: 1
                          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: &ref_5
                              tierId:
                                type: string
                                description: 'Unique tier identifier (format: badgeName-tierLevel)'
                                example: traveler-bronze
                              tierName:
                                type: string
                                description: Human-readable tier name
                                enum:
                                  - Starter
                                  - Bronze
                                  - Silver
                                  - Gold
                                  - Platinum
                                  - Diamond
                                example: Bronze
                              description:
                                type: string
                                description: Specific requirements to achieve this tier
                                example: 50 Genesis City scenes explored (for at least 1 min)
                              criteria:
                                type: object
                                description: Tier completion criteria
                                properties:
                                  steps:
                                    type: integer
                                    description: Number of steps/actions required to achieve this tier
                                    example: 50
                                additionalProperties: true
                              assets:
                                type: object
                                description: Asset URLs for badge imagery in different formats
                                properties: &ref_0
                                  2d:
                                    type: object
                                    description: 2D badge assets
                                    properties:
                                      normal:
                                        type: string
                                        description: Standard 2D badge image URL
                                        example: https://badges.decentraland.org/assets/badge-2d.png
                                    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: &ref_6
                              - tierId
                              - tierName
                              - description
                        assets:
                          type: object
                          description: Asset URLs for badge imagery in different formats
                          properties: *ref_0
                      required: &ref_4
                        - id
                        - name
                        - description
                        - category
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                description: Error response object
                properties: &ref_1
                  error:
                    type: string
                    description: Human-readable error message
                    example: Badge not found
                  code:
                    type: string
                    description: Machine-readable error code
                    example: BADGE_NOT_FOUND
                required: &ref_2
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                description: Error response object
                properties: *ref_1
                required: *ref_2
  /badges/{id}:
    get:
      tags:
        - Badges
      summary: Get specific badge details
      description: |
        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`
      operationId: getBadgeDetails
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Unique badge identifier (e.g., 'dclcitizen', 'traveler', 'fashionista')
          example: traveler
      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: *ref_3
                        required: *ref_4
        '404':
          description: Badge with the specified ID was not found
          content:
            application/json:
              schema:
                type: object
                description: Error response object
                properties: *ref_1
                required: *ref_2
  /badges/{id}/tiers:
    get:
      tags:
        - Badges
      summary: Get badge tier progression
      description: |
        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.
      operationId: getBadgeTiers
      security: []
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: Badge identifier
          example: traveler
      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: *ref_5
                          required: *ref_6
        '404':
          description: Badge with the specified ID was not found
          content:
            application/json:
              schema:
                type: object
                description: Error response object
                properties: *ref_1
                required: *ref_2
  /users/{address}/badges:
    get:
      tags:
        - User Progress
      summary: Get user's badge progress
      description: |
        Returns detailed progress information for all badges associated with a specific user address.

        This endpoint provides comprehensive tracking data including:
        - **Achieved badges**: Badges the user has earned (at least one step completed)
        - **Progress tracking**: Current steps completed vs. target steps for next tier
        - **Tier progression**: For tiered badges, shows which tiers have been completed and when
        - **Completion status**: Whether the badge/tier is fully completed
        - **Asset information**: Current badge/tier images and metadata

        The response is divided into two categories:
        - `achieved`: Badges with at least one step or tier completed
        - `notAchieved`: Badges not yet started (only included if `includeNotAchieved=true`)

        For tiered badges, the progress tracks movement through tiers (Starter → Bronze → Silver → Gold → Platinum → Diamond).
        For single-tier badges, it tracks completion of a specific criteria.
      operationId: getUserBadges
      security: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: User's Ethereum address (wallet address)
          example: '0x1234567890123456789012345678901234567890'
        - name: includeNotAchieved
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: If true, includes badges that the user hasn't started working toward yet
      responses:
        '200':
          description: Successfully retrieved user's badge progress
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    description: Container for user's badge progress, divided by achievement status
                    properties: &ref_9
                      achieved:
                        type: array
                        description: Badges with at least one step or tier completed
                        items:
                          type: object
                          description: Detailed progress tracking for a single badge
                          properties: &ref_7
                            id:
                              type: string
                              description: Badge identifier
                              example: traveler
                            name:
                              type: string
                              description: Badge name
                              example: Traveler
                            description:
                              type: string
                              description: Badge description
                            category:
                              type: string
                              enum:
                                - Explorer
                                - Collector
                                - Creator
                                - Socializer
                                - Builder
                              description: Badge category
                            isTier:
                              type: boolean
                              description: Whether this badge has multiple tiers
                            completedAt:
                              type:
                                - number
                                - 'null'
                              description: Unix timestamp (milliseconds) when badge was fully completed, null if not completed
                            assets:
                              type: object
                              description: Asset URLs for badge imagery in different formats
                              properties: *ref_0
                            progress:
                              type: object
                              description: Progress tracking information
                              properties:
                                achievedTiers:
                                  type: array
                                  description: List of tiers achieved (only for tiered badges)
                                  items:
                                    type: object
                                    properties:
                                      tierId:
                                        type: string
                                        example: traveler-bronze
                                      completedAt:
                                        type: number
                                        description: Unix timestamp (milliseconds) when tier was completed
                                stepsDone:
                                  type: integer
                                  description: Number of steps/actions completed
                                  example: 75
                                nextStepsTarget:
                                  type:
                                    - integer
                                    - 'null'
                                  description: Target steps for next tier/completion (null if fully completed)
                                  example: 250
                                totalStepsTarget:
                                  type: integer
                                  description: Total steps required for full badge completion
                                  example: 10000
                                lastCompletedTierAt:
                                  type:
                                    - number
                                    - 'null'
                                  description: Timestamp of last completed tier (tiered badges only)
                                lastCompletedTierName:
                                  type:
                                    - string
                                    - 'null'
                                  description: Name of last completed tier (tiered badges only)
                                  example: Bronze
                                lastCompletedTierImage:
                                  type:
                                    - string
                                    - 'null'
                                  description: Image URL of last completed tier (tiered badges only)
                          required: &ref_8
                            - id
                            - name
                            - description
                            - category
                            - isTier
                            - progress
                      notAchieved:
                        type: array
                        description: Badges not yet started (only included if includeNotAchieved=true)
                        items:
                          type: object
                          description: Detailed progress tracking for a single badge
                          properties: *ref_7
                          required: *ref_8
                    required: &ref_10
                      - achieved
                      - notAchieved
        '404':
          description: User address not found or invalid
          content:
            application/json:
              schema:
                type: object
                description: Error response object
                properties: *ref_1
                required: *ref_2
  /users/{address}/preview:
    get:
      tags:
        - User Progress
      summary: Get user's latest achieved badges
      description: |
        Returns a lightweight preview of the user's most recently achieved badges.

        This endpoint is optimized for displaying user achievements in UI components like profile cards or leaderboards. It provides:
        - Badge ID, name, and display image
        - Tier name (if applicable) for the most recently achieved tier
        - Appropriate badge imagery for the current tier level

        Unlike `/users/{address}/badges`, this endpoint:
        - Returns only completed badges (no progress tracking)
        - Includes only the latest achievements
        - Has a lighter payload optimized for quick loading
        - Is ideal for preview cards, tooltips, and summary displays
      operationId: getUserBadgesPreview
      security: []
      parameters:
        - name: address
          in: path
          required: true
          schema:
            type: string
          description: User's Ethereum address
          example: '0x1234567890123456789012345678901234567890'
      responses:
        '200':
          description: Successfully retrieved user's badge preview
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      latestAchievedBadges:
                        type: array
                        items:
                          type: object
                          description: Lightweight badge preview for UI display
                          properties: &ref_11
                            id:
                              type: string
                              description: Badge identifier
                              example: traveler
                            name:
                              type: string
                              description: Badge name
                              example: Traveler
                            tierName:
                              type:
                                - string
                                - 'null'
                              description: Name of the achieved tier (if applicable)
                              example: Bronze
                            image:
                              type: string
                              description: URL to the badge or tier image
                              example: https://badges.decentraland.org/assets/traveler-bronze-2d.png
                          required: &ref_12
                            - id
                            - name
                            - image
        '404':
          description: User address not found or invalid
          content:
            application/json:
              schema:
                type: object
                description: Error response object
                properties: *ref_1
                required: *ref_2
  /categories:
    get:
      tags:
        - Categories
      summary: Get all badge categories
      description: |
        Returns the complete list of badge categories used to classify achievements in Decentraland.

        Available categories:
        - **Explorer**: Badges related to discovering and exploring scenes, locations, and the metaverse
        - **Collector**: Badges for acquiring and equipping wearables, emotes, and other digital assets
        - **Creator**: Badges for publishing original content like wearables, emotes, and collections
        - **Socializer**: Badges for social interactions, event attendance, and community engagement
        - **Builder**: Badges for creating and deploying scenes in Genesis City

        These categories help organize badges and allow users to filter achievements by type of activity.
      operationId: getBadgeCategories
      security: []
      responses:
        '200':
          description: Successfully retrieved badge categories
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      categories:
                        type: array
                        items:
                          type: string
                          enum:
                            - Explorer
                            - Collector
                            - Creator
                            - Socializer
                            - Builder
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                description: Error response object
                properties: *ref_1
                required: *ref_2
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                description: Error response object
                properties: *ref_1
                required: *ref_2
  /status:
    get:
      tags:
        - Health
      summary: Get API health status
      description: |
        Returns the current health and operational status of the Badges API service.

        This endpoint is used for:
        - Health checks and monitoring
        - Uptime verification
        - Load balancer health checks
        - Service availability confirmation

        A 200 response indicates the service is operational and ready to serve requests.
      operationId: getStatus
      security: []
      responses:
        '200':
          description: Service is healthy and operational
          content:
            application/json:
              schema:
                type: object
                description: Service health status response
                properties: &ref_13
                  status:
                    type: string
                    description: Health status indicator
                    example: ok
                    enum:
                      - ok
                      - degraded
                      - down
                  timestamp:
                    type: string
                    format: date-time
                    description: ISO 8601 timestamp of the status check
                    example: '2025-10-28T12:00:00Z'
                required: &ref_14
                  - status
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                description: Error response object
                properties: *ref_1
                required: *ref_2
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                description: Error response object
                properties: *ref_1
                required: *ref_2
components:
  schemas:
    Badge:
      type: object
      description: Complete badge definition including metadata, criteria, tiers, and assets
      properties: *ref_3
      required: *ref_4
    BadgeTier:
      type: object
      description: A single tier within a progressive badge system
      properties: *ref_5
      required: *ref_6
    BadgeProgress:
      type: object
      description: Detailed progress tracking for a single badge
      properties: *ref_7
      required: *ref_8
    BadgesProgresses:
      type: object
      description: Container for user's badge progress, divided by achievement status
      properties: *ref_9
      required: *ref_10
    UserBadgePreview:
      type: object
      description: Lightweight badge preview for UI display
      properties: *ref_11
      required: *ref_12
    BadgeAssets:
      type: object
      description: Asset URLs for badge imagery in different formats
      properties: *ref_0
    Status:
      type: object
      description: Service health status response
      properties: *ref_13
      required: *ref_14
    Error:
      type: object
      description: Error response object
      properties: *ref_1
      required: *ref_2
