HIBP API v3

openapi: 3.0.3
info:
  title: Have I Been Pwned API v3
  description: |
    The Have I Been Pwned (HIBP) API allows the list of pwned accounts (email addresses, domains,
    passwords, and stealer log entries) to be quickly searched via REST. Authenticated endpoints
    require an `hibp-api-key` header. All requests must send a `user-agent` header that accurately
    identifies the consuming application. Subscriptions range from Pwned 1 to Pwned 5.
  version: "3.0.0"
  contact:
    name: Have I Been Pwned
    url: https://haveibeenpwned.com/API/v3
  license:
    name: Creative Commons Attribution 4.0
    url: https://creativecommons.org/licenses/by/4.0/
servers:
  - url: https://haveibeenpwned.com/api/v3
    description: HIBP Production API
tags:
  - name: Breached Accounts
    description: Lookup breaches affecting an email address.
  - name: Breaches
    description: Browse breach metadata in the HIBP corpus.
  - name: Data Classes
    description: Enumerate classes of data exposed across breaches.
  - name: Pastes
    description: Lookup pastes referencing an email address.
  - name: Stealer Logs
    description: Search infostealer malware corpora by email or domain.
  - name: Domain Search
    description: Verify and search domains you control.
  - name: Subscription
    description: Inspect the calling key's subscription state.
security:
  - ApiKeyAuth: []
paths:
  /breachedaccount/{account}:
    get:
      tags: [Breached Accounts]
      summary: Get Breaches For An Account
      description: |
        Returns all breaches for the supplied email address. Requires a valid `hibp-api-key`
        and a descriptive `user-agent` header.
      operationId: getBreachesForAccount
      parameters:
        - $ref: '#/components/parameters/AccountPath'
        - name: truncateResponse
          in: query
          description: When true (default) only breach names are returned. Set false for full breach objects.
          required: false
          schema:
            type: boolean
            default: true
        - name: domain
          in: query
          description: Filter results to breaches against the supplied domain.
          required: false
          schema:
            type: string
        - name: IncludeUnverified
          in: query
          description: When true (default), unverified breaches are included in results.
          required: false
          schema:
            type: boolean
            default: true
      responses:
        '200':
          description: One or more breaches were found.
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                    - $ref: '#/components/schemas/BreachName'
                    - $ref: '#/components/schemas/Breach'
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /breachedaccount/range/{hashPrefix}:
    get:
      tags: [Breached Accounts]
      summary: Get Breaches By K-Anonymity Range
      description: |
        Returns email-account breach matches using a k-anonymity model. Supply the first six
        characters of the SHA-1 hash of the email address. Available on Pwned 2 and higher.
      operationId: getBreachesByRange
      parameters:
        - name: hashPrefix
          in: path
          required: true
          description: First six characters of the SHA-1 hash of the email address (uppercase).
          schema:
            type: string
            pattern: '^[A-F0-9]{6}$'
      responses:
        '200':
          description: A list of hash suffixes and the websites that exposed them.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BreachedAccountRangeEntry'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /breaches:
    get:
      tags: [Breaches]
      summary: Get All Breaches In The System
      description: Returns the complete corpus of breaches currently in HIBP.
      operationId: listBreaches
      security: []
      parameters:
        - name: Domain
          in: query
          description: Filter the response to breaches against the supplied domain.
          required: false
          schema:
            type: string
        - name: IsSpamList
          in: query
          description: Filter to spam-list breaches only when true.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: All breaches matching the filters.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Breach'
  /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'
        '404': { $ref: '#/components/responses/NotFound' }
  /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'
  /dataclasses:
    get:
      tags: [Data Classes]
      summary: Get All Data Classes
      description: Returns the alphabetically ordered list of data classes that may be exposed in breaches.
      operationId: listDataClasses
      security: []
      responses:
        '200':
          description: An alphabetically ordered list of data class names.
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
  /pasteaccount/{account}:
    get:
      tags: [Pastes]
      summary: Get Pastes For An Account
      description: Returns all pastes referencing the supplied email address, sorted chronologically (newest first).
      operationId: getPastesForAccount
      parameters:
        - $ref: '#/components/parameters/AccountPath'
      responses:
        '200':
          description: A list of pastes referencing the account.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Paste'
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/TooManyRequests' }
  /stealerlogsbyemail/{email}:
    get:
      tags: [Stealer Logs]
      summary: Get Stealer Log Domains For An Email
      description: Returns website domains exposed in stealer log corpora for the supplied email address.
      operationId: getStealerLogsByEmail
      parameters:
        - name: email
          in: path
          required: true
          schema: { type: string, format: email }
      responses:
        '200':
          description: An alphabetically ordered list of website domains.
          content:
            application/json:
              schema:
                type: array
                items: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /stealerlogsbywebsitedomain/{domain}:
    get:
      tags: [Stealer Logs]
      summary: Get Stealer Log Emails For A Website Domain
      description: Returns email addresses exposed against a verified website domain.
      operationId: getStealerLogsByWebsiteDomain
      parameters:
        - name: domain
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: An alphabetically ordered list of email addresses.
          content:
            application/json:
              schema:
                type: array
                items: { type: string, format: email }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /stealerlogsbyemaildomain/{domain}:
    get:
      tags: [Stealer Logs]
      summary: Get Stealer Log Aliases For An Email Domain
      description: Returns email aliases (and the website domains exposing them) for the supplied verified email domain.
      operationId: getStealerLogsByEmailDomain
      parameters:
        - name: domain
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: A map of alias to exposed website domains.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
  /breacheddomain/{domain}:
    get:
      tags: [Domain Search]
      summary: Get Breached Email Addresses For A Domain
      description: Returns email aliases on the supplied verified domain that appear in breaches.
      operationId: getBreachedDomain
      parameters:
        - name: domain
          in: path
          required: true
          schema: { type: string }
      responses:
        '200':
          description: A map of alias to breach names.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: array
                  items: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
  /subscribeddomains:
    get:
      tags: [Domain Search]
      summary: List Subscribed Domains
      description: Returns the domains the calling subscription is currently monitoring.
      operationId: listSubscribedDomains
      responses:
        '200':
          description: A list of subscribed domains.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SubscribedDomain'
        '401': { $ref: '#/components/responses/Unauthorized' }
  /domainverification/generateDnsToken:
    post:
      tags: [Domain Search]
      summary: Generate A DNS Verification Token
      description: Generates a DNS TXT record value used to verify ownership of a domain.
      operationId: generateDnsToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainVerificationRequest'
      responses:
        '200':
          description: A DNS TXT record value.
          content:
            application/json:
              schema:
                type: object
                properties:
                  txtRecordValue: { type: string }
  /domainverification/verifyDnsToken:
    post:
      tags: [Domain Search]
      summary: Verify A DNS Verification Token
      description: Triggers DNS verification of a previously generated TXT record.
      operationId: verifyDnsToken
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainVerificationRequest'
      responses:
        '200':
          description: Domain verification succeeded.
  /domainverification/sendEmail:
    post:
      tags: [Domain Search]
      summary: Send A Domain Verification Email
      description: Sends a verification email to a standard alias on the domain.
      operationId: sendDomainVerificationEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DomainEmailVerificationRequest'
      responses:
        '200':
          description: Verification email sent.
  /subscription/status:
    get:
      tags: [Subscription]
      summary: Get Subscription Status
      description: Returns details about the calling key's current subscription including RPM and feature flags.
      operationId: getSubscriptionStatus
      responses:
        '200':
          description: The current subscription details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatus'
        '401': { $ref: '#/components/responses/Unauthorized' }
components:
  securitySchemes:
    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.
  parameters:
    AccountPath:
      name: account
      in: path
      required: true
      description: URL-encoded email address to search.
      schema:
        type: string
        format: email
  responses:
    BadRequest:
      description: The request was malformed (e.g. invalid email format).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: The `hibp-api-key` header is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: |
        The request is forbidden. Common causes include a missing `user-agent` header,
        querying an unverified domain, or a feature not included in the calling subscription.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No record matched the supplied identifier.
    TooManyRequests:
      description: |
        Rate limit exceeded. Inspect the `retry-after` header to determine when to retry.
      headers:
        retry-after:
          schema: { type: integer }
          description: Seconds to wait before retrying.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    BreachName:
      type: object
      description: Truncated breach representation returned by default from /breachedaccount.
      properties:
        Name:
          type: string
          description: Pascal-cased stable name of the breach.
      required: [Name]
    Breach:
      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]
    BreachedAccountRangeEntry:
      type: object
      description: A k-anonymity breached-account match.
      properties:
        hashSuffix:
          type: string
          description: Remaining 34 characters of the SHA-1 hash of the email address.
        websites:
          type: array
          items: { type: string }
          description: Breach names that contain the matching email address.
      required: [hashSuffix, websites]
    Paste:
      type: object
      description: A paste referencing an email address.
      properties:
        Source:
          type: string
          description: Paste source service (e.g. Pastebin, Pastie, Slexy, Ghostbin).
        Id:
          type: string
          description: Source-specific identifier of the paste.
        Title:
          type: string
          nullable: true
          description: Title of the paste, if available.
        Date:
          type: string
          format: date-time
          nullable: true
          description: When the paste was published.
        EmailCount:
          type: integer
          description: Number of email addresses found in the paste.
      required: [Source, Id, EmailCount]
    SubscribedDomain:
      type: object
      description: A domain monitored by the calling subscription.
      properties:
        DomainName:
          type: string
          description: Fully qualified domain name.
        PwnCount:
          type: integer
          nullable: true
          description: Total pwned email count on the domain.
        PwnCountExcludingSpamLists:
          type: integer
          nullable: true
          description: Pwned email count excluding spam lists.
        PwnCountExcludingSpamListsAtLastSubscriptionRenewal:
          type: integer
          nullable: true
          description: Pwned count excluding spam lists at the last renewal.
        NextSubscriptionRenewal:
          type: string
          format: date-time
          nullable: true
          description: Next renewal date for the domain subscription.
      required: [DomainName]
    DomainVerificationRequest:
      type: object
      properties:
        DomainName:
          type: string
          description: Fully qualified domain to verify.
      required: [DomainName]
    DomainEmailVerificationRequest:
      type: object
      properties:
        DomainName:
          type: string
          description: Fully qualified domain to verify.
        EmailAlias:
          type: string
          description: Local part of the email alias (admin, hostmaster, info, security, webmaster).
      required: [DomainName, EmailAlias]
    SubscriptionStatus:
      type: object
      description: Details of the calling key's subscription.
      properties:
        SubscriptionName:
          type: string
          description: Human readable subscription name (e.g. Pwned 1, Pwned 5).
        Description:
          type: string
          description: Subscription description.
        SubscribedUntil:
          type: string
          format: date-time
          description: Expiration date of the subscription.
        Rpm:
          type: integer
          description: Requests per minute allowed.
        DomainSearchMaxBreachedAccounts:
          type: integer
          description: Maximum breached accounts returned by a domain search.
        MaxBreachedDomains:
          type: integer
          nullable: true
          description: Maximum number of breached domains monitorable.
        IncludesStealerLogs:
          type: boolean
          description: Whether the subscription unlocks the stealer log APIs.
        IncludesBulkDomainAdd:
          type: boolean
          description: Whether bulk domain add is enabled.
        IncludesAutoSubdomainVerification:
          type: boolean
          description: Whether subdomains auto-verify.
        IncludesCustomerDomains:
          type: boolean
          description: Whether customer domains can be monitored.
        IncludesKAnon:
          type: boolean
          description: Whether k-anonymity endpoints are enabled.
      required: [SubscriptionName]
    Error:
      type: object
      description: Standard HIBP error payload.
      properties:
        statusCode: { type: integer }
        message: { type: string }
      required: [statusCode, message]