openapi: 3.2.0
info:
  title: Namegender Account API
  version: 1.0.0
  contact:
    url: https://namegender.com/docs
  description: 'Operations tagged Account across 2 of this provider''s published API definitions: namegender-api-openapi.json, openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://namegender.com
  description: Production
security:
- bearerAuth: []
- apiKeyHeader: []
tags:
- name: Account
  description: Credit balance and key status.
paths:
  /api/v1/me:
    get:
      tags:
      - Account
      summary: Credit balance and account status
      description: Costs no credits. Use it to show remaining balance in your own dashboard, or to check a key is live before a large batch.
      operationId: getAccount
      responses:
        '200':
          description: Account status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '401':
          $ref: '#/components/responses/401'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
    servers:
    - url: https://namegender.com
      description: Production
components:
  schemas:
    AccountResponse:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Account email address.
        credits_remaining:
          type: integer
          description: Purchased credits plus whatever is left of today's free quota.
        purchased_credits:
          type: integer
          description: Paid balance. Credits stay on your balance until you spend them.
        free_today:
          type: integer
          description: Free credits left today. Resets at midnight UTC.
        free_daily_limit:
          type: integer
          description: Free credits granted per day.
        lifetime_requests:
          type: integer
          description: Requests made with this account so far.
        data_version:
          type:
          - string
          - 'null'
          description: Current name-dataset snapshot.
    Error:
      type: object
      description: The one error shape. Returned by every endpoint at every failing status code.
      required:
      - error
      - message
      - docs
      properties:
        error:
          type: string
          description: Machine-readable and stable. **Branch on this.** New codes may be added over time, so treat an unrecognised value as a generic failure rather than crashing.
          enum:
          - missing_key
          - invalid_key
          - revoked_key
          - blocked
          - email_not_verified
          - ip_not_allowed
          - proxy_secret_required
          - forbidden
          - no_credits
          - missing_input
          - invalid_input
          - too_many_items
          - ai_consent_required
          - unknown_endpoint
          - method_not_allowed
          - payload_too_large
          - rate_limited
          - batch_not_found
          - batch_not_startable
          - batch_not_finished
          - batch_in_progress
          - result_gone
          - too_many_batches
          - not_ready
          - server_error
        message:
          type: string
          description: Human-readable, translated into the caller's language. Wording can change; never parse or compare it.
        request_id:
          type:
          - string
          - 'null'
          description: Quote this in support requests.
          example: req_9c1f5b2a7e0d4a13
        docs:
          type: string
          format: uri
          description: Link to this error in the documentation.
        errors:
          type: object
          description: Field-level detail. Present on validation failures only.
          additionalProperties:
            type: array
            items:
              type: string
        retry_after:
          type: integer
          description: Seconds to wait. Present on 429 only, and mirrored in the `Retry-After` header.
  responses:
    '500':
      description: Unexpected server error. Nothing was charged. Quote `request_id` if it persists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '401':
      description: 'No usable API key. Codes: `missing_key`, `invalid_key`, `revoked_key`.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    '429':
      description: 'Rate limit exceeded, or too many file jobs running at once. Wait `retry_after` seconds. Codes: `rate_limited`, `too_many_batches`.'
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Recommended: `Authorization: Bearer <key>`.'
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: Alternative header form, for clients that cannot set `Authorization`. Keys are never read from the query string or the request body.
x-refined-from:
- namegender-api-openapi.json
- openapi.json