openapi: 3.1.0
info:
  title: CPFHub.io API
  version: "1.0"
  description: |
    REST API for querying Brazilian CPF (Cadastro de Pessoas Físicas) identity data.
    Returns full name, gender, and date of birth for a given CPF number.

    Common use cases: KYC, user onboarding, fraud prevention, form auto-fill.

    Authentication: include your API Key in the `x-api-key` request header.
    Obtain your key at https://app.cpfhub.io.
  contact:
    name: CPFHub.io Support
    url: https://cpfhub.io
    email: suporte@cpfhub.io
  license:
    name: Proprietary
    url: https://cpfhub.io/termos
  x-llms-txt: https://cpfhub.io/llms.txt
  x-openapi-json: https://cpfhub.io/openapi.json
  x-openapi-yaml: https://cpfhub.io/openapi.yaml

servers:
  - url: https://api.cpfhub.io
    description: Production

security:
  - ApiKeyAuth: []

tags:
  - name: CPF
    description: Identity lookup by CPF number

paths:
  /v1/cpf/{cpf}:
    get:
      operationId: getCpf
      summary: Look up a CPF
      description: |
        Returns identity data associated with the given CPF number.

        - **Not found (404) does not consume a credit.** Only successful 200 responses are billed.
        - The `gender` field is inferred from the full name.
        - The `cpf` field in the response is always returned in the formatted pattern XXX.XXX.XXX-XX.
      tags:
        - CPF
      parameters:
        - name: cpf
          in: path
          required: true
          description: |
            CPF number with or without formatting.
            Valid inputs: `12345678909` or `123.456.789-09`.
          schema:
            type: string
            pattern: '^\d{11}$|^\d{3}\.\d{3}\.\d{3}-\d{2}$'
            example: "12345678909"
      responses:
        "200":
          description: CPF found — identity data returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CPFResponse'
              example:
                success: true
                data:
                  cpf: "123.456.789-09"
                  name: "John Doe"
                  nameUpper: "JOHN DOE"
                  gender: "M"
                  birthDate: "15/06/1990"
                  day: 15
                  month: 6
                  year: 1990
        "400":
          description: Invalid CPF format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INVALID_CPF_FORMAT
                  message: "Invalid CPF format. Expected 11 digits."
        "401":
          description: Missing or invalid API Key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INVALID_API_KEY
                  message: "The provided API key is invalid."
        "403":
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INSUFFICIENT_CREDITS
                  message: "Your account has no remaining credits."
        "404":
          description: CPF not found — does not consume a credit
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: CPF_NOT_FOUND
                  message: "CPF not found in our database."
        "422":
          description: CPF check digits are invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INVALID_CPF_DIGITS
                  message: "CPF check digits are invalid."
        "429":
          description: Rate limit exceeded
          headers:
            Retry-After:
              description: Seconds until the next request will be accepted
              schema:
                type: integer
                example: 1
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: RATE_LIMIT_EXCEEDED
                  message: "Too many requests. Please retry after 1 second."
        "500":
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                success: false
                error:
                  code: INTERNAL_ERROR
                  message: "An unexpected error occurred. Please try again."

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: |
        Obtain your API Key at https://app.cpfhub.io.
        Include it in every request: `x-api-key: your-api-key`

  schemas:
    CPFResponse:
      type: object
      required: [success, data]
      description: Successful CPF lookup response
      properties:
        success:
          type: boolean
          description: Always `true` for 200 responses
          example: true
        data:
          $ref: '#/components/schemas/CPFData'

    CPFData:
      type: object
      required: [cpf, name, nameUpper, gender, birthDate, day, month, year]
      description: Identity data associated with the CPF
      properties:
        cpf:
          type: string
          description: Formatted CPF (XXX.XXX.XXX-XX)
          example: "123.456.789-09"
        name:
          type: string
          description: Full name in title case
          example: "John Doe"
        nameUpper:
          type: string
          description: Full name in uppercase
          example: "JOHN DOE"
        gender:
          type: string
          enum: [M, F]
          description: Gender inferred from the full name (M = male, F = female)
          example: "M"
        birthDate:
          type: string
          description: Date of birth in DD/MM/YYYY format
          pattern: '^\d{2}/\d{2}/\d{4}$'
          example: "15/06/1990"
        day:
          type: integer
          minimum: 1
          maximum: 31
          description: Day of birth
          example: 15
        month:
          type: integer
          minimum: 1
          maximum: 12
          description: Month of birth
          example: 6
        year:
          type: integer
          minimum: 1900
          description: Year of birth
          example: 1990

    ErrorResponse:
      type: object
      required: [success, error]
      description: Error response
      properties:
        success:
          type: boolean
          description: Always `false` for error responses
          example: false
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
              description: Machine-readable error code
              enum:
                - INVALID_CPF_FORMAT
                - INVALID_CPF_DIGITS
                - MISSING_API_KEY
                - INVALID_API_KEY
                - INSUFFICIENT_CREDITS
                - CPF_NOT_FOUND
                - RATE_LIMIT_EXCEEDED
                - INTERNAL_ERROR
              example: "CPF_NOT_FOUND"
            message:
              type: string
              description: Human-readable error description
              example: "CPF not found in our database."