> ## Documentation Index
> Fetch the complete documentation index at: https://docs.finowl.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Check a password

> Returns how many times a password appears in known breaches, using Finowl intelligence.
The password is never stored, logged or returned, and it is matched by partial hash
(k-anonymity), so the full password or its full hash is never used in the lookup.

Costs **1 credit**.




## OpenAPI

````yaml /api-reference/openapi.yaml post /v1/breaches/password
openapi: 3.1.0
info:
  title: Finowl API
  version: '1.0'
  description: >
    Check emails and passwords against known data breaches, and predict gender
    from

    names, emails and usernames. Every endpoint is a JSON `POST` authenticated
    with a

    bearer API key.
servers:
  - url: https://api.finowl.co
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Breaches
    description: Check whether an email or password appears in known data breaches.
  - name: Gender
    description: >-
      Predict gender from a name, email or username, one at a time or in
      batches.
paths:
  /v1/breaches/password:
    post:
      tags:
        - Breaches
      summary: Check a password
      description: >
        Returns how many times a password appears in known breaches, using
        Finowl intelligence.

        The password is never stored, logged or returned, and it is matched by
        partial hash

        (k-anonymity), so the full password or its full hash is never used in
        the lookup.


        Costs **1 credit**.
      operationId: checkPasswordBreaches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
                - password
              properties:
                password:
                  type: string
                  minLength: 1
                  maxLength: 4096
                  description: >-
                    The password to check, exactly as the user typed it.
                    Whitespace and case are preserved.
                  example: P@ssw0rd
      responses:
        '200':
          description: The check completed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PasswordBreachResult'
              examples:
                breached:
                  summary: Common password
                  value:
                    breached: true
                    count: 133211
                clean:
                  summary: Not found
                  value:
                    breached: false
                    count: 0
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '502':
          $ref: '#/components/responses/ProviderFailed'
        '503':
          $ref: '#/components/responses/Unavailable'
        '504':
          $ref: '#/components/responses/Unconfirmed'
components:
  schemas:
    PasswordBreachResult:
      type: object
      required:
        - breached
        - count
      properties:
        breached:
          type: boolean
          description: '`true` when the password appears at least once.'
        count:
          type: integer
          minimum: 0
          description: How many times the password appears across known breaches.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
          properties:
            code:
              type: string
              description: >-
                A stable, machine-readable error code. See the Errors page for
                the full list.
              example: invalid_input
  responses:
    InvalidInput:
      description: The request body is not valid. Fix the request before trying again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_input
    Unauthorized:
      description: The API key is missing, malformed or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
    TooManyRequests:
      description: >
        `rate_limited` (too many requests this minute), `quota_exceeded` (not
        enough credits) or

        `provider_rate_limited` (Finowl intelligence is busy). Check the
        `Retry-After` header.
      headers:
        Retry-After:
          description: Seconds to wait before trying again.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
    ProviderFailed:
      description: >-
        Finowl intelligence could not complete the lookup. The request was
        charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: provider_unavailable
    Unavailable:
      description: Finowl intelligence is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: provider_unavailable
    Unconfirmed:
      description: >-
        Finowl intelligence did not answer in time. The lookup may or may not
        have run, and the request was charged.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: provider_response_unconfirmed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Your Finowl API key, for example `finowl_3f9a...`. Create keys in the
        dashboard under **API Keys**.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.