hibp-openapi.yaml

openapi: 3.0.0
info:
  title: Have I Been Pwned API
  description: Check if an email address or password has been exposed in a data breach
  version: 3.0.0
servers:
  - url: https://haveibeenpwned.com/api/v3
    description: Have I Been Pwned API v3
paths:
  /breachedaccount/{account}:
    get:
      summary: Check if an email address has been in a data breach
      description: Returns all breaches a particular account (email address) has been involved in
      operationId: checkBreachedAccount
      parameters:
        - name: account
          in: path
          required: true
          schema:
            type: string
          description: The email address to check
          example: "test@example.com"
        - name: truncateResponse
          in: query
          required: false
          schema:
            type: boolean
            default: false
          description: Return only breach names (true) or full details (false)
        - name: domain
          in: query
          required: false
          schema:
            type: string
          description: Filter results to a specific domain
      responses:
        '200':
          description: Account found in breaches
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    Name:
                      type: string
                      description: Breach name
                    Title:
                      type: string
                      description: Breach title
                    Domain:
                      type: string
                      description: Breached domain
                    BreachDate:
                      type: string
                      format: date
                      description: Date of the breach
                    AddedDate:
                      type: string
                      format: date-time
                      description: When the breach was added to HIBP
                    ModifiedDate:
                      type: string
                      format: date-time
                      description: Last modification date
                    PwnCount:
                      type: integer
                      description: Number of accounts in breach
                    Description:
                      type: string
                      description: Breach description
                    DataClasses:
                      type: array
                      items:
                        type: string
                      description: Types of data exposed
                    IsVerified:
                      type: boolean
                      description: Whether the breach is verified
                    IsFabricated:
                      type: boolean
                      description: Whether the breach is fabricated
                    IsSensitive:
                      type: boolean
                      description: Whether the breach is sensitive
                    IsRetired:
                      type: boolean
                      description: Whether the breach is retired
                    IsSpamList:
                      type: boolean
                      description: Whether the breach is a spam list
                    IsMalware:
                      type: boolean
                      description: Whether the breach involved malware
                    LogoPath:
                      type: string
                      description: Path to breach logo
        '404':
          description: No breaches found for this account (good news!)
        '400':
          description: Bad request - invalid email address
        '401':
          description: Unauthorized - invalid API key
        '403':
          description: Forbidden - no user agent specified
        '429':
          description: Rate limit exceeded
  /breach/{name}:
    get:
      summary: Get details about a specific breach
      description: Returns details about a single breach by breach name
      operationId: getBreachDetails
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
          description: The breach name
          example: "Adobe"
      responses:
        '200':
          description: Breach details
          content:
            application/json:
              schema:
                type: object
                properties:
                  Name:
                    type: string
                  Title:
                    type: string
                  Domain:
                    type: string
                  BreachDate:
                    type: string
                    format: date
                  AddedDate:
                    type: string
                    format: date-time
                  ModifiedDate:
                    type: string
                    format: date-time
                  PwnCount:
                    type: integer
                  Description:
                    type: string
                  DataClasses:
                    type: array
                    items:
                      type: string
                  IsVerified:
                    type: boolean
                  IsFabricated:
                    type: boolean
                  IsSensitive:
                    type: boolean
                  IsRetired:
                    type: boolean
                  IsSpamList:
                    type: boolean
                  IsMalware:
                    type: boolean
                  LogoPath:
                    type: string
        '404':
          description: Breach not found
        '400':
          description: Bad request
  /breaches:
    get:
      summary: Get all breaches in the system
      description: Returns all breaches in the HIBP database
      operationId: getAllBreaches
      parameters:
        - name: domain
          in: query
          required: false
          schema:
            type: string
          description: Filter breaches by domain
      responses:
        '200':
          description: List of all breaches
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    Name:
                      type: string
                    Title:
                      type: string
                    Domain:
                      type: string
                    BreachDate:
                      type: string
                      format: date
                    AddedDate:
                      type: string
                      format: date-time
                    PwnCount:
                      type: integer
                    Description:
                      type: string
                    DataClasses:
                      type: array
                      items:
                        type: string
                    IsVerified:
                      type: boolean
        '400':
          description: Bad request
components:
  securitySchemes:
    HibpApiKey:
      type: apiKey
      in: header
      name: hibp-api-key
      description: Have I Been Pwned API Key (get one at https://haveibeenpwned.com/API/Key)
security:
  - HibpApiKey: []