openapi: 3.0.3
info:
  title: Have I Been Pwned API v3 Breach Pasteaccount 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: Pasteaccount
paths:
  /pasteaccount/{account}:
    servers:
    - url: https://haveibeenpwned.com/api/v3
    get:
      summary: Get all pastes for an account
      description: Available on Core, Pro, and High RPM subscriptions. Searches for pastes containing the supplied email address. The address is not case-sensitive, is trimmed of leading or trailing whitespace, and should always be URL encoded. This is an authenticated API requiring both the hibp-api-key and user-agent headers.
      parameters:
      - $ref: '#/components/parameters/UserAgent'
      - name: account
        in: path
        required: true
        schema:
          type: string
        description: URL-encoded email address to search for pastes
      security:
      - HibpApiKey: []
      responses:
        '200':
          description: List of pastes, sorted chronologically with the newest paste first
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Paste'
        '400':
          description: Bad request — invalid account 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.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found — no pastes for account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Too many requests — rate limit exceeded
          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
      - High RPM
      tags:
      - Pasteaccount
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:
    Paste:
      type: object
      properties:
        Source:
          type: string
          description: 'The paste service the record was retrieved from. Current values are: Pastebin, Pastie, Slexy, Ghostbin, QuickLeak, JustPaste, AdHocUrl, PermanentOptOut, OptOut.'
        Id:
          type: string
          description: The ID of the paste as it was given at the source service. Combined with the 'Source' attribute, this can be used to resolve the URL of the paste.
        Title:
          type: string
          nullable: true
          description: The title of the paste as observed on the source site. This may be null and if so will be omitted from the response.
        Date:
          type: string
          format: date-time
          nullable: true
          description: The date and time (precision to the second) that the paste was posted. This is taken directly from the paste site when this information is available but may be null if no date is published.
        EmailCount:
          type: integer
          description: The number of emails that were found when processing the paste.
      required:
      - Source
      - Id
      - EmailCount
    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