openapi: 3.0.3
info:
  title: Have I Been Pwned API v3 Breach Breacheddomain API
  description: Version 3 of the Have I Been Pwned API. Authenticated APIs for breaches by account, pastes, domain search, domain verification, stealer logs, and subscription status require both the hibp-api-key and user-agent headers. Availability varies by subscription tier and is noted per operation. The Pwned Passwords range API is free and does not require authentication.
  version: 3.0.0
  license:
    name: Creative Commons Attribution 4.0 International
    url: https://creativecommons.org/licenses/by/4.0/
servers:
- url: https://haveibeenpwned.com/api/v3
  description: HIBP API v3 server
- url: https://api.pwnedpasswords.com
  description: Pwned Passwords k-Anonymity API (no authentication required)
tags:
- name: Breacheddomain
paths:
  /breacheddomain/{domain}:
    servers:
    - url: https://haveibeenpwned.com/api/v3
    get:
      summary: Get all breached email addresses for a domain
      description: Available on Core and Pro subscriptions. Returns all breached email aliases on a verified domain and the breach names they have appeared in. The domain must already have been added to the domain search dashboard and successfully verified. Sensitive breaches are returned because this API is only available after domain control has been demonstrated.
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - name: domain
        in: path
        required: true
        schema:
          type: string
        description: The domain to be searched for. Must be a verified domain in the domain search dashboard.
      security:
      - HibpApiKey: []
      responses:
        '200':
          description: Mapping of email aliases to breach names. For each breached email address on the domain, only the alias is returned along with each breach it has appeared in. Only the name attribute of the breach is returned.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items:
                    type: string
              example:
                alias1:
                - Adobe
                alias2:
                - Adobe
                - Gawker
                - Stratfor
                alias3:
                - AshleyMadison
        '400':
          description: Bad request — invalid domain format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — the hibp-api-key header was missing, malformed, or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — no user agent has been specified in the request, the domain has not been verified in the domain search dashboard, or the current subscription is out of scope for the domain size or monitored-domain count.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found — the domain does not have any email addresses in any breaches
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — the rate limit has been exceeded. Typically, there is no need to query a domain unless a new breach has been added since the last query.
          headers:
            Retry-After:
              description: Seconds until retry
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-hibp-subscription-tiers:
      - Core
      - Pro
      tags:
      - Breacheddomain
components:
  parameters:
    UserAgent:
      name: user-agent
      in: header
      required: true
      description: User agent string identifying the consuming application. Required on all documented requests, including unauthenticated endpoints; missing user agents may receive HTTP 403 responses.
      schema:
        type: string
  schemas:
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
      required:
      - statusCode
      - message
      description: Standard error response returned by most authenticated HIBP APIs.
  securitySchemes:
    HibpApiKey:
      type: apiKey
      in: header
      name: hibp-api-key
      description: HIBP API key passed in the hibp-api-key header. Paid APIs require a 32-character hexadecimal value. On supported test-only endpoints, any 32-character hexadecimal value can be used as a test key for the hibp-integration-tests.com domain.
externalDocs:
  description: Full API documentation and acceptable use policy
  url: https://haveibeenpwned.com/API/v3