Have I Been Pwned Subscription API

openapi: 3.2.0
info:
  title: Have I Been Pwned Subscription API
  version: 3.0.0
  description: 'Operations tagged Subscription 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: Subscription
paths:
  /subscription/status:
    servers:
    - url: https://haveibeenpwned.com/api/v3
    get:
      summary: Get current subscription status
      description: Available on Core, Pro, and High RPM subscriptions. Returns details of the current subscription represented by the supplied hibp-api-key, including plan capabilities such as stealer-log access, breached-account k-anonymity access, bulk domain add features, and monitored-domain limits.
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      security:
      - HibpApiKey: []
      responses:
        '200':
          description: Current subscription capabilities and limits for the supplied API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriptionStatus'
        '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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found — no active subscription was found for the supplied API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                statusCode: 404
                message: No active subscription found.
      x-hibp-subscription-tiers:
      - Core
      - Pro
      - High RPM
      tags:
      - Subscription
      operationId: getSubscriptionStatus
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
      required:
      - statusCode
      - message
      description: Standard error response returned by most authenticated HIBP APIs.
    SubscriptionStatus:
      type: object
      properties:
        SubscriptionName:
          type: string
          description: The name representing the current plan and level, for example "Core 1", "Pro 2", or "High RPM 12000".
        Description:
          type: string
          description: A human-readable sentence explaining the scope of the subscription.
        SubscribedUntil:
          type: string
          format: date-time
          description: The date and time the current subscription ends in ISO 8601 format.
        Rpm:
          type: integer
          description: The rate limit in requests per minute. This applies to the rate the breach search by email address API can be requested.
        DomainSearchMaxBreachedAccounts:
          type:
          - integer
          - 'null'
          description: The size of the largest domain the subscription can search. This is expressed in the total number of breached email addresses on the domain, excluding those that appear solely in spam lists.
        MaxBreachedDomains:
          type:
          - integer
          - 'null'
          description: The number of domains the subscription can add, regardless of their size. A null value indicates there is no max domain limit.
        IncludesStealerLogs:
          type: boolean
          description: Indicates if the subscription includes access to the stealer logs APIs.
        IncludesBulkDomainAdd:
          type: boolean
          description: Indicates if the subscription includes access to the APIs that add domains via DNS or email verification.
        IncludesAutoSubdomainVerification:
          type: boolean
          description: Indicates if the subscription allows subdomains to be automatically added after the apex domain has already been verified.
        IncludesCustomerDomains:
          type: boolean
          description: Indicates if the subscription allows the domains of customers to be added.
        IncludesKAnon:
          type: boolean
          description: Indicates if the subscription includes access to the breached-account k-anonymity API.
      required:
      - SubscriptionName
      - Description
      - SubscribedUntil
      - Rpm
      - DomainSearchMaxBreachedAccounts
      - MaxBreachedDomains
      - IncludesStealerLogs
      - IncludesBulkDomainAdd
      - IncludesAutoSubdomainVerification
      - IncludesCustomerDomains
      - IncludesKAnon
    Error_2:
      type: object
      description: Standard HIBP error payload.
      properties:
        statusCode:
          type: integer
        message:
          type: string
      required:
      - statusCode
      - message
    SubscriptionStatus_2:
      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
          - 'null'
          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
  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:
    Unauthorized:
      description: The `hibp-api-key` header is missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error_2'
  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