openapi: 3.0.3
info:
  title: Hypixel Public Housing Player Data API
  x-logo:
    url: https://api.hypixel.net/assets/images/logo.png
    altText: Hypixel Logo
    href: '#'
  description: "# Introduction\nThis is the official Hypixel API documentation. [Hypixel Website](https://hypixel.net/) - [GitHub Repo](https://github.com/HypixelDev/PublicAPI) - [API Help Forum](https://hypixel.net/forums/api-help.111/)\n\nAll use of the API must conform to the [API policies](https://developer.hypixel.net/policies), violation of these policies may lead to applications being revoked or users banned from the API.\n## Limits\nAPI keys are limited to a maximum amount of requests per 5 minute intervals. These limits will depend on the type of application that the key is assigned to.\n\nEndpoints which require the use of an API key will also respond with headers to assist with managing the rate limit:\n- 'RateLimit-Limit' - The limit of requests per minute for the provided API key.\n- 'RateLimit-Remaining' - The remaining amount of requests allowed for the current minute.\n- 'RateLimit-Reset' - The amount of seconds until the next minute and the reset of the API key usages.\n\n## GameTypes\n| ID | Type Name      | Database Name | Clean Name           |\n |----|----------------|---------------|----------------------|\n | 2  | QUAKECRAFT     | Quake         | Quake                |\n | 3  | WALLS          | Walls         | Walls                |\n | 4  | PAINTBALL      | Paintball     | Paintball            |\n | 5  | SURVIVAL_GAMES | HungerGames   | Blitz Survival Games |\n | 6  | TNTGAMES       | TNTGames      | TNT Games            |\n | 7  | VAMPIREZ       | VampireZ      | VampireZ             |\n | 13 | WALLS3         | Walls3        | Mega Walls           |\n | 14 | ARCADE         | Arcade        | Arcade               |\n | 17 | ARENA          | Arena         | Arena                |\n | 20 | UHC            | UHC           | UHC Champions        |\n | 21 | MCGO           | MCGO          | Cops and Crims       |\n | 23 | BATTLEGROUND   | Battleground  | Warlords             |\n | 24 | SUPER_SMASH    | SuperSmash    | Smash Heroes         |\n | 25 | GINGERBREAD    | GingerBread   | Turbo Kart Racers    |\n | 26 | HOUSING        | Housing       | Housing              |\n | 51 | SKYWARS        | SkyWars       | SkyWars              |\n | 52 | TRUE_COMBAT    | TrueCombat    | Crazy Walls          |\n | 54 | SPEED_UHC      | SpeedUHC      | Speed UHC            |\n | 55 | SKYCLASH       | SkyClash      | SkyClash             |\n | 56 | LEGACY         | Legacy        | Classic Games        |\n | 57 | PROTOTYPE      | Prototype     | Prototype            |\n | 58 | BEDWARS        | Bedwars       | Bed Wars             |\n | 59 | MURDER_MYSTERY | MurderMystery | Murder Mystery       |\n | 60 | BUILD_BATTLE   | BuildBattle   | Build Battle         |\n | 61 | DUELS          | Duels         | Duels                |\n | 63 | SKYBLOCK       | SkyBlock      | SkyBlock             |\n | 64 | PIT            | Pit           | Pit                  |\n | 65 | REPLAY         | Replay        | Replay               |\n | 67 | SMP            | SMP           | SMP                  |\n | 68 | WOOL_GAMES     | WoolGames     | Wool Wars            |\n\n### Storage\nGames store their respective stats and data in a Player's `stats` collection. The game's specific data is held within a JSON object named after it's `Database Name` (seen above.)\n### GameType Notes\n* Clean names are what is displayed to the user when referencing the name.\n* Database names or IDs are used when the API references a specific GameType.\n## Notes\n\n### Date and Time\nGenerally dates are stored as a Unix Epoch times in milliseconds.\n### Response Format\nResponses are served in JSON format.\n### UUID Parameters\nAll uuid parameters support both dashed and undashed versions.\n### SkyBlock items and inventories\nItems and inventory data are stored as a base64 encoded string containing gzipped nbt data.\nIf a method is missing important information about an item or inventory, you should try checking this!\n>Note: the base64 string may contain a unicode escape for non-alphabetical symbols, and some programming languages may have silent defects when interpreting the string. \n\n# Authentication\n\n<!-- ReDoc-Inject: <security-definitions> -->"
  version: v2
  termsOfService: https://hypixel.net/tos
  contact:
    name: Hypixel Support
    url: https://developer.hypixel.net
  x-jentic-source-url: https://api.hypixel.net/
  x-generated-from: jentic-public-apis
  x-last-validated: '2026-05-30'
servers:
- url: https://api.hypixel.net
security:
- ApiKey: []
tags:
- name: Player Data
  description: Hypixel network player profiles, recent games, online status, friends, and guild lookups.
paths:
  /v2/player:
    get:
      summary: Hypixel Data of a Specific Player, Including Game Stats
      tags:
      - Player Data
      security:
      - ApiKey: []
      parameters:
      - in: query
        name: uuid
        schema:
          type: string
        required: true
        example: ad8fefaa8351454bb739a4eaa872173f
        description: The uuid parameter.
      responses:
        '200':
          description: Get player's data
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  player:
                    type: object
                    properties:
                      uuid:
                        type: string
                        example: 3fa85f6457174562b3fc2c963f66afa6
                      displayname:
                        type: string
                        nullable: true
                      rank:
                        type: string
                        nullable: true
                        enum:
                        - ADMIN
                        - MODERATOR
                        - HELPER
                        - NORMAL
                      packageRank:
                        type: string
                        nullable: true
                        enum:
                        - MVP_PLUS
                        - MVP
                        - VIP_PLUS
                        - VIP
                        - NONE
                      newPackageRank:
                        type: string
                        nullable: true
                        enum:
                        - MVP_PLUS
                        - MVP
                        - VIP_PLUS
                        - VIP
                        - NONE
                      monthlyPackageRank:
                        type: string
                        nullable: true
                        enum:
                        - SUPERSTAR
                        - NONE
                      firstLogin:
                        type: number
                        nullable: true
                      lastLogin:
                        type: number
                        nullable: true
                      lastLogout:
                        type: number
                        nullable: true
                      stats:
                        type: object
                        nullable: true
              examples:
                GetPlayer200Example:
                  summary: Default getPlayer 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    player:
                      uuid: 3fa85f6457174562b3fc2c963f66afa6
                      displayname: ExamplePlayer
                      rank: ADMIN
                      packageRank: MVP_PLUS
                      newPackageRank: MVP_PLUS
                      monthlyPackageRank: SUPERSTAR
        '400':
          $ref: '#/components/responses/DataMissing'
        '403':
          $ref: '#/components/responses/InvalidKey'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getPlayer
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Data of a specific player, including game stats
  /v2/recentgames:
    get:
      summary: Hypixel The Recently Played Games of a Specific Player
      tags:
      - Player Data
      security:
      - ApiKey: []
      parameters:
      - in: query
        name: uuid
        schema:
          type: string
        required: true
        example: ad8fefaa8351454bb739a4eaa872173f
        description: The uuid parameter.
      responses:
        '200':
          description: Get player's recent game
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  uuid:
                    type: string
                    format: uuid
                  games:
                    type: array
                    items:
                      type: object
                      properties:
                        date:
                          type: number
                          format: int64
                        gameType:
                          type: string
                        mode:
                          type: string
                        map:
                          type: string
                        ended:
                          type: number
                          format: int64
              examples:
                GetRecentgames200Example:
                  summary: Default getRecentgames 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    uuid: ad8fefaa8351454bb739a4eaa872173f
                    games:
                    - date: 1.0
                      gameType: example
                      mode: example
                      map: example
                      ended: 1.0
        '400':
          $ref: '#/components/responses/DataMissing'
        '403':
          $ref: '#/components/responses/InvalidKey'
        '422':
          $ref: '#/components/responses/MalformedData'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getRecentgames
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: The recently played games of a specific player
  /v2/status:
    get:
      summary: Hypixel The Current Online Status of a Specific Player
      tags:
      - Player Data
      security:
      - ApiKey: []
      parameters:
      - in: query
        name: uuid
        schema:
          type: string
        required: true
        example: ad8fefaa8351454bb739a4eaa872173f
        description: The uuid parameter.
      responses:
        '200':
          description: Get player status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  uuid:
                    type: string
                    format: uuid
                    example: ad8fefaa8351454bb739a4eaa872173f
                  session:
                    type: object
                    properties:
                      online:
                        type: boolean
                      gameType:
                        type: string
                      mode:
                        type: string
                      map:
                        type: string
              examples:
                GetStatus200Example:
                  summary: Default getStatus 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    uuid: ad8fefaa8351454bb739a4eaa872173f
                    session:
                      online: true
                      gameType: example
                      mode: example
                      map: example
        '400':
          $ref: '#/components/responses/DataMissing'
        '403':
          $ref: '#/components/responses/InvalidKey'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getStatus
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: The current online status of a specific player
  /v2/guild:
    get:
      summary: Hypixel Retrieve a Guild by a Player, Id, or Name
      tags:
      - Player Data
      security:
      - ApiKey: []
      parameters:
      - in: query
        name: id
        schema:
          type: string
          format: objectid
        example: 5fcbf9d9d295e80a766f3b14
        description: The id parameter.
      - in: query
        name: player
        schema:
          type: string
          format: uuid
        example: ad8fefaa8351454bb739a4eaa872173f
        description: The player parameter.
      - in: query
        name: name
        schema:
          type: string
        example: ExamplePlayer
        description: The name parameter.
      responses:
        '200':
          description: Get guild information
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                  guild:
                    type: object
              examples:
                GetGuild200Example:
                  summary: Default getGuild 200 response
                  x-microcks-default: true
                  value:
                    success: true
                    guild: {}
        '400':
          $ref: '#/components/responses/DataMissing'
        '403':
          $ref: '#/components/responses/InvalidKey'
        '429':
          $ref: '#/components/responses/RateLimited'
      operationId: getGuild
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
      description: Retrieve a Guild by a player, id, or name
components:
  responses:
    RateLimited:
      description: A request limit has been reached, usually this is due to the limit on the key being reached but can also be triggered by a global throttle.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              cause:
                type: string
                example: Key throttle
              throttle:
                type: boolean
                example: true
              global:
                type: boolean
                description: When this boolean exists and is true, the throttle occurring is a global throttle applied to all users
                example: true
    MalformedData:
      description: Some data provided is invalid.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              cause:
                type: string
                example: Malformed UUID
    InvalidKey:
      description: Access is forbidden, usually due to an invalid API key being used.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              cause:
                type: string
                example: Invalid API key
    DataMissing:
      description: Some data is missing, this is usually a field.
      content:
        application/json:
          schema:
            type: object
            properties:
              success:
                type: boolean
                example: false
              cause:
                type: string
                example: Missing one or more fields [...]
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: API-Key
      description: Obtained via the [Hypixel Developer Dashboard](https://developer.hypixel.net) when creating an application. You can also request higher limits for production applications in this dashboard.