Have I Been Pwned Breaches API

openapi: 3.2.0
info:
  title: Have I Been Pwned Breaches API
  version: 3.0.0
  description: 'Operations tagged Breaches across 2 of this provider''s published API definitions: have-i-been-pwned-openapi.json, hibp-openapi.yml. Each path carries the servers of the definition it was published in.'
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: Breaches
paths:
  /breaches:
    servers:
    - url: https://haveibeenpwned.com/api/v3
    get:
      summary: Get all breaches in the system
      description: Returns the full breach catalogue. This endpoint is unauthenticated, but it still requires a user-agent header.
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - name: domain
        in: query
        schema:
          type: string
        description: Filters the result set to only breaches against the domain specified. It is possible that one site (and consequently domain), is compromised on multiple occasions.
      - name: isSpamList
        in: query
        schema:
          type: boolean
        description: Filters the result set to only breaches that either are or are not flagged as a spam list.
      responses:
        '200':
          description: List of all breaches, sorted alphabetically by the title of the breach
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Breach'
        '403':
          description: Forbidden — missing user agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      tags:
      - Breaches
      operationId: getBreaches
      x-operation-id-source: derived
  /breach/{name}:
    get:
      tags:
      - Breaches
      summary: Get A Single Breach By Name
      description: Returns the metadata for a single breach identified by its stable Pascal-cased name.
      operationId: getBreachByName
      security: []
      parameters:
      - name: name
        in: path
        required: true
        description: Pascal-cased stable name of the breach (e.g. `Adobe`).
        schema:
          type: string
      responses:
        '200':
          description: The breach record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Breach_2'
        '404':
          $ref: '#/components/responses/NotFound'
    servers:
    - url: https://haveibeenpwned.com/api/v3
      description: HIBP Production API
  /latestbreach:
    get:
      tags:
      - Breaches
      summary: Get The Most Recently Added Breach
      description: Returns the breach most recently added to HIBP.
      operationId: getLatestBreach
      security: []
      responses:
        '200':
          description: The most recently added breach.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Breach_2'
    servers:
    - url: https://haveibeenpwned.com/api/v3
      description: HIBP Production API
components:
  schemas:
    Breach:
      type: object
      properties:
        Name:
          type: string
          description: A Pascal-cased name representing the breach which is unique across all other breaches. This value never changes and may be used to name dependent assets (such as images) but should not be shown directly to end users (see the 'Title' attribute instead).
        Title:
          type: string
          description: A descriptive title for the breach suitable for displaying to end users. It's unique across all breaches but individual values may change in the future (i.e. if another breach occurs against an organisation already in the system).
        Domain:
          type: string
          description: The domain of the primary website the breach occurred on. This may be used for identifying other assets external systems may have for the site.
        BreachDate:
          type: string
          format: date
          description: The date (with no time) the breach originally occurred on in ISO 8601 format. This is not always accurate — frequently breaches are discovered and reported long after the original incident. Use this attribute as a guide only.
        AddedDate:
          type: string
          format: date-time
          description: The date and time (precision to the minute) the breach was added to the system in ISO 8601 format.
        ModifiedDate:
          type: string
          format: date-time
          description: The date and time (precision to the minute) the breach was modified in ISO 8601 format. This will only differ from the AddedDate attribute if other attributes represented here are changed or data in the breach itself is changed (i.e. additional data is identified and loaded). It is always either equal to or greater then the AddedDate attribute, never less than.
        PwnCount:
          type: integer
          description: The total number of accounts loaded into the system. This is usually less than the total number reported by the media due to duplication or other data integrity issues in the source data.
        Description:
          type: string
          description: Contains an overview of the breach represented in HTML markup. The description may include markup such as emphasis and strong tags as well as hyperlinks.
        DataClasses:
          type: array
          items:
            type: string
          description: This attribute describes the nature of the data compromised in the breach and contains an alphabetically ordered string array of impacted data classes.
        IsVerified:
          type: boolean
          description: Indicates that the breach is considered unverified. An unverified breach may not have been hacked from the indicated website. An unverified breach is still loaded into HIBP when there's sufficient confidence that a significant portion of the data is legitimate.
        IsFabricated:
          type: boolean
          description: Indicates that the breach is considered fabricated. A fabricated breach is unlikely to have been hacked from the indicated website and usually contains a large amount of manufactured data. However, it still contains legitimate email addresses and asserts that the account owners were compromised in the alleged breach.
        IsSensitive:
          type: boolean
          description: Indicates if the breach is considered sensitive. The public API will not return any accounts for a breach flagged as sensitive.
        IsRetired:
          type: boolean
          description: Indicates if the breach has been retired. This data has been permanently removed and will not be returned by the API.
        IsSpamList:
          type: boolean
          description: Indicates if the breach is considered a spam list. This flag has no impact on any other attributes but it means that the data has not come as a result of a security compromise.
        IsMalware:
          type: boolean
          description: Indicates if the breach is sourced from malware. This flag has no impact on any other attributes, it merely flags that the data was sourced from a malware campaign rather than a security compromise of an online service.
        IsSubscriptionFree:
          type: boolean
          description: Indicates if the breach is subscription-free. This flag has no impact on any other attributes, it is only used when running a domain search where a sufficiently sized subscription isn't present.
        IsStealerLog:
          type: boolean
          description: Indicates if the breach is sourced from stealer logs. A breach with this flag also has the domains that appear in the logs loaded against each email address. This data can be accessed via the stealer logs API.
        LogoPath:
          type: string
          format: uri
          description: A URI that specifies where a logo for the breached service can be found. Logos are always in PNG format.
        Attribution:
          type:
          - string
          - 'null'
          description: Sometimes requested by the party that provides the data to HIBP.
      required:
      - Name
      - Title
      - Domain
      - BreachDate
      - AddedDate
      - ModifiedDate
      - PwnCount
      - Description
      - DataClasses
      - IsVerified
      - IsFabricated
      - IsSensitive
      - IsRetired
      - IsSpamList
      - IsMalware
      - IsSubscriptionFree
      - IsStealerLog
      - LogoPath
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
      required:
      - statusCode
      - message
      description: Standard error response returned by most authenticated HIBP APIs.
    Breach_2:
      type: object
      description: Full metadata record describing a breach in HIBP.
      properties:
        Name:
          type: string
          description: Stable Pascal-cased identifier; never changes.
        Title:
          type: string
          description: Descriptive breach title suitable for UI display.
        Domain:
          type: string
          description: Primary website domain associated with the breach.
        BreachDate:
          type: string
          format: date
          description: Approximate date the breach occurred (ISO 8601).
        AddedDate:
          type: string
          format: date-time
          description: When the breach was loaded into HIBP.
        ModifiedDate:
          type: string
          format: date-time
          description: Last modification timestamp; always greater than or equal to AddedDate.
        PwnCount:
          type: integer
          description: Approximate number of email addresses loaded for the breach.
        Description:
          type: string
          description: HTML-formatted description of the breach.
        DataClasses:
          type: array
          items:
            type: string
          description: Alphabetically ordered list of data classes exposed in the breach.
        IsVerified:
          type: boolean
          description: Whether the breach has been verified.
        IsFabricated:
          type: boolean
          description: Whether the breach data is likely fabricated.
        IsSensitive:
          type: boolean
          description: Whether the breach is flagged sensitive (not returned in public APIs).
        IsRetired:
          type: boolean
          description: Whether the breach has been retired from public listings.
        IsSpamList:
          type: boolean
          description: Whether the source is a spam list rather than a credential breach.
        IsMalware:
          type: boolean
          description: Whether the breach originates from malware activity.
        IsStealerLog:
          type: boolean
          description: Whether the breach is sourced from stealer logs.
        IsSubscriptionFree:
          type: boolean
          description: Whether the breach is queryable without an HIBP subscription.
        LogoPath:
          type: string
          format: uri
          description: URI to the breach logo PNG.
        Attribution:
          type: string
          description: Optional human-readable attribution for the breach source.
      required:
      - Name
      - Title
      - Domain
      - BreachDate
      - AddedDate
      - ModifiedDate
      - PwnCount
  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
  responses:
    NotFound:
      description: No record matched the supplied identifier.
  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.
    ApiKeyAuth:
      type: apiKey
      in: header
      name: hibp-api-key
      description: '32-character hexadecimal API key issued at https://haveibeenpwned.com/API/Key.

        Required for all account, paste, stealer log, domain search, and subscription endpoints.

        '
externalDocs:
  description: Full API documentation and acceptable use policy
  url: https://haveibeenpwned.com/API/v3
x-refined-from:
- have-i-been-pwned-openapi.json
- hibp-openapi.yml