openapi: 3.2.0
info:
  title: GenderAPI Public Gender inference API
  version: 1.0.0
  summary: Gender inference and phone validation endpoints.
  description: API-owner-approved contract derived from the public English documentation and verified backend handlers. Gender values are probabilistic inferences, not verified identity. Publication remains controlled by the separate GEO release gate.
  termsOfService: https://www.genderapi.io/terms
  contact:
    url: https://www.genderapi.io/contact
servers:
- url: https://api.genderapi.io
  description: Production API
tags:
- name: Gender inference
paths:
  /api:
    post:
      tags:
      - Gender inference
      operationId: inferGenderFromName
      summary: Infer gender from one name
      description: 'Canonical documentation: https://www.genderapi.io/docs-gender-from-name-single'
      security:
      - bearerAuth: []
      x-documentation-url: https://www.genderapi.io/docs-gender-from-name-single
      x-credit-cost: One lookup; AI fallback may have different usage accounting. Confirm current terms.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - name
              properties:
                name:
                  type: string
                  minLength: 1
                country:
                  type: string
                  pattern: ^[A-Z]{2}$
                  description: ISO 3166-1 alpha-2 country code used as regional context.
                  examples:
                  - US
                askToAI:
                  type: boolean
                  default: false
            example:
              name: Alice
              country: US
              askToAI: true
      responses:
        '200':
          description: Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SingleLookupResponse'
                - $ref: '#/components/schemas/Error'
              example:
                status: true
                used_credits: 1
                remaining_credits: 4999
                expires: 1743659200
                q: Alice
                name: Alice
                gender: female
                country: US
                total_names: 10234
                probability: 98
                duration: 4ms
        '400':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/name/multi/country:
    post:
      tags:
      - Gender inference
      operationId: inferGenderFromNames
      summary: Infer gender from multiple names
      description: 'Canonical documentation: https://www.genderapi.io/docs-gender-from-name-multiple'
      security:
      - bearerAuth: []
      x-documentation-url: https://www.genderapi.io/docs-gender-from-name-multiple
      x-credit-cost: Credits are consumed per processed record, not per HTTP request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - data
              properties:
                data:
                  type: array
                  minItems: 1
                  maxItems: 200
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - name
                    properties:
                      name:
                        type: string
                        minLength: 1
                      country:
                        type: string
                        pattern: ^[A-Z]{2}$
                        description: ISO 3166-1 alpha-2 country code used as regional context.
                        examples:
                        - US
                      id:
                        oneOf:
                        - type: string
                        - type: integer
                        description: Caller record identifier.
            example:
              data:
              - name: Andrea
                country: DE
                id: '123'
      responses:
        '200':
          description: Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BatchLookupResponse'
                - $ref: '#/components/schemas/Error'
              example:
                status: true
                used_credits: 1
                remaining_credits: 4999
                expires: 1743659200
                names:
                - q: Andrea
                  name: andrea
                  gender: female
                  country: US
                  total_names: 1234
                  probability: 92
                  id: '123'
                duration: 5ms
        '400':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-live-verification:
        observedAt: '2026-09-14'
        result: A 200-record request returned all 200 results with used_credits 200. A 201-record request returned HTTP 200 with status false and errno 92.
        partialProcessing: A mixed request containing one valid record and one record without the required name returned status true, one result, and used_credits 1. An empty-string name was processed and returned gender "null".
  /api/email:
    post:
      tags:
      - Gender inference
      operationId: inferGenderFromEmail
      summary: Extract a name and infer gender from one email address
      description: 'Canonical documentation: https://www.genderapi.io/docs-gender-from-email-single'
      security:
      - bearerAuth: []
      x-documentation-url: https://www.genderapi.io/docs-gender-from-email-single
      x-credit-cost: One lookup; AI fallback may have different usage accounting. Confirm current terms.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - email
              properties:
                email:
                  type: string
                  minLength: 1
                country:
                  type: string
                  pattern: ^[A-Z]{2}$
                  description: ISO 3166-1 alpha-2 country code used as regional context.
                  examples:
                  - US
                askToAI:
                  type: boolean
                  default: false
            example:
              email: alice.smith@example.com
              country: US
      responses:
        '200':
          description: Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SingleLookupResponse'
                - $ref: '#/components/schemas/Error'
              example:
                status: true
                used_credits: 1
                remaining_credits: 4999
                expires: 1743659200
                q: alice.smith@example.com
                name: Alice
                gender: female
                country: US
                total_names: 10234
                probability: 98
                duration: 4ms
        '400':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/email/multi/country:
    post:
      tags:
      - Gender inference
      operationId: inferGenderFromEmails
      summary: Extract names and infer gender from multiple email addresses
      description: 'Canonical documentation: https://www.genderapi.io/docs-gender-from-email-multiple'
      security:
      - bearerAuth: []
      x-documentation-url: https://www.genderapi.io/docs-gender-from-email-multiple
      x-credit-cost: Credits are consumed per processed record, not per HTTP request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - data
              properties:
                data:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - email
                    properties:
                      email:
                        type: string
                        minLength: 1
                      country:
                        type: string
                        pattern: ^[A-Z]{2}$
                        description: ISO 3166-1 alpha-2 country code used as regional context.
                        examples:
                        - US
                      id:
                        oneOf:
                        - type: string
                        - type: integer
                        description: Caller record identifier.
            example:
              data:
              - email: anna.smith@example.com
                country: US
                id: '123'
      responses:
        '200':
          description: Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BatchLookupResponse'
                - $ref: '#/components/schemas/Error'
              example:
                status: true
                used_credits: 1
                remaining_credits: 4999
                expires: 1743659200
                names:
                - q: anna.smith@example.com
                  name: Anna
                  gender: female
                  country: US
                  total_names: 1234
                  probability: 92
                  id: '123'
                duration: 5ms
        '400':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/username:
    post:
      tags:
      - Gender inference
      operationId: inferGenderFromUsername
      summary: Extract a name and infer gender from one username
      description: 'Canonical documentation: https://www.genderapi.io/docs-gender-from-username-single'
      security:
      - bearerAuth: []
      x-documentation-url: https://www.genderapi.io/docs-gender-from-username-single
      x-credit-cost: One lookup; AI options may have different usage accounting. Confirm current terms.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - username
              properties:
                username:
                  type: string
                  minLength: 1
                country:
                  type: string
                  pattern: ^[A-Z]{2}$
                  description: ISO 3166-1 alpha-2 country code used as regional context.
                  examples:
                  - US
                askToAI:
                  type: boolean
                  default: false
                forceToGenderize:
                  type: boolean
                  default: false
            example:
              username: anna_smith88
              country: US
      responses:
        '200':
          description: Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/SingleLookupResponse'
                - $ref: '#/components/schemas/Error'
              example:
                status: true
                used_credits: 1
                remaining_credits: 4999
                expires: 1743659200
                q: anna_smith88
                name: Anna
                gender: female
                country: US
                total_names: 10234
                probability: 98
                duration: 4ms
        '400':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/username/multi/country:
    post:
      tags:
      - Gender inference
      operationId: inferGenderFromUsernames
      summary: Extract names and infer gender from multiple usernames
      description: 'Canonical documentation: https://www.genderapi.io/docs-gender-from-username-multiple'
      security:
      - bearerAuth: []
      x-documentation-url: https://www.genderapi.io/docs-gender-from-username-multiple
      x-credit-cost: Credits are consumed per processed record, not per HTTP request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required:
              - data
              properties:
                data:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    additionalProperties: false
                    required:
                    - username
                    properties:
                      username:
                        type: string
                        minLength: 1
                      country:
                        type: string
                        pattern: ^[A-Z]{2}$
                        description: ISO 3166-1 alpha-2 country code used as regional context.
                        examples:
                        - US
                      id:
                        oneOf:
                        - type: string
                        - type: integer
                        description: Caller record identifier.
            example:
              data:
              - username: anna_smith88
                country: US
                id: '123'
      responses:
        '200':
          description: Application response. Inspect status before reading result fields; live verification observed validation and authentication errors inside HTTP 200 responses.
          content:
            application/json:
              schema:
                oneOf:
                - $ref: '#/components/schemas/BatchLookupResponse'
                - $ref: '#/components/schemas/Error'
              example:
                status: true
                used_credits: 1
                remaining_credits: 4999
                expires: 1743659200
                names:
                - q: anna_smith88
                  name: Anna
                  gender: female
                  country: US
                  total_names: 1234
                  probability: 92
                  id: '123'
                duration: 5ms
        '400':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Authentication rejected by a gender-inference handler. Current backend compatibility behavior uses HTTP 404 with an Error body for this branch.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Request rejected. Branch on errno rather than errmsg text.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    SingleLookupResponse:
      allOf:
      - type: object
        required:
        - status
        properties:
          status:
            type: boolean
            const: true
          used_credits:
            type: integer
            minimum: 0
            description: Credits consumed for processed records.
          remaining_credits:
            type: integer
            minimum: 0
          expires:
            type: integer
            description: Package expiration as a UNIX timestamp.
          duration:
            type: string
            examples:
            - 4ms
      - type: object
        properties:
          name:
            type: string
          q:
            type: string
            description: Original submitted value.
          gender:
            type: string
            enum:
            - male
            - female
            - 'null'
            description: Probabilistic result. An unresolved input is returned as the literal string "null", not JSON null.
          country:
            type: string
            pattern: ^[A-Z]{2}$
            description: ISO 3166-1 alpha-2 country code used as regional context.
            examples:
            - US
          total_names:
            type: integer
            minimum: 0
          probability:
            type: integer
            minimum: 0
            maximum: 100
          id:
            oneOf:
            - type: string
            - type: integer
            description: Caller record identifier.
    Error:
      type: object
      additionalProperties: true
      required:
      - status
      - errno
      - errmsg
      properties:
        status:
          type: boolean
          const: false
        errno:
          type: integer
          enum:
          - 50
          - 90
          - 91
          - 92
          - 93
          - 94
          - 99
        errmsg:
          type: string
      example:
        status: false
        errno: 94
        errmsg: invalid or missing key
      x-error-catalog:
      - errno: 50
        message: access denied
        action: Review API-key IP or referrer restrictions.
      - errno: 90
        message: invalid country code
        action: Validate an ISO 3166-1 alpha-2 country code.
      - errno: 91
        message: required input not set
        action: Add the endpoint's required name, email, or username.
      - errno: 92
        message: batch limit exceeded
        action: Split input according to the documented endpoint limit.
      - errno: 93
        message: query limit reached
        action: Pause lookups and review the account quota.
      - errno: 94
        message: invalid or missing key
        action: Check server-side credential injection.
      - errno: 99
        message: API key has expired
        action: Review or renew the package before retrying.
    BatchLookupResponse:
      type: object
      required:
      - status
      - names
      properties:
        status:
          type: boolean
          const: true
        used_credits:
          type: integer
          minimum: 0
          description: Credits consumed for processed records.
        remaining_credits:
          type: integer
          minimum: 0
        expires:
          type: integer
          description: Package expiration as a UNIX timestamp.
        duration:
          type: string
          examples:
          - 4ms
        names:
          type: array
          description: Contains a result for every processed input, including unresolved results with gender "null". Live verification observed that a malformed entry missing the required name was omitted while valid entries were processed.
          items:
            type: object
            properties:
              name:
                type: string
              q:
                type: string
                description: Original submitted value.
              gender:
                type: string
                enum:
                - male
                - female
                - 'null'
                description: Probabilistic result. An unresolved input is returned as the literal string "null", not JSON null.
              country:
                type: string
                pattern: ^[A-Z]{2}$
                description: ISO 3166-1 alpha-2 country code used as regional context.
                examples:
                - US
              total_names:
                type: integer
                minimum: 0
              probability:
                type: integer
                minimum: 0
                maximum: 100
              id:
                oneOf:
                - type: string
                - type: integer
                description: Caller record identifier.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Recommended server-side API-key transport.
    apiKeyQuery:
      type: apiKey
      in: query
      name: key
      description: Supported by documented GET endpoints; keep requests server-side.
x-lifecycle-policy:
  approvedAt: '2026-09-15'
  canonicalTransport: Bearer authentication on POST operations; query-key on documented GET compatibility operations.
  compatibility: Existing legacy GET, authentication transports, JSONP or alternate response shapes, HTTP error mappings, and errno values remain operational until measured, announced, and migrated.
  breakingChange: Removing or changing an accepted request transport, operation, response shape, field type, HTTP/application-error mapping, or errno value is a breaking change.
  minimumNoticeMonths: 6
  criticalEnterpriseNoticeMonths: 12
  noticeChannels:
  - developer documentation
  - account email
  sunsetSignaling:
  - documentation deprecation notice
  - Sunset HTTP header where technically applicable