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]