Hail Whoami API

openapi: 3.2.0
info:
  title: Hail Whoami API
  description: 'Give your AI agent a voice, a real phone number, and an inbox.


    This file is the source of truth for the Go CLI. Regenerate it after

    changing API routes — see docs/public/contributing.md.'
  version: 0.1.0
servers:
- url: https://api.hail.so
  description: Hail Cloud
tags:
- name: Whoami
paths:
  /v1/whoami:
    get:
      tags:
      - Whoami
      summary: Get Whoami
      description: 'Identify the caller: auth kind, organization, and (if resolvable) user.


        Useful for an agent that needs the human''s address to put in

        Reply-To, since the bearer token itself only carries an organization.

        user_id/email/name come back null for a shared-key

        (HAIL_API_KEY) call, which has no individual user behind it.'
      operationId: get_whoami_v1_whoami_get
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WhoamiResponse'
        '429':
          description: Rate limited. This caller exceeded the general request-rate ceiling. Retry after the Retry-After header (seconds).
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
            RateLimit-Limit:
              description: The request ceiling for the current window.
              schema:
                type: integer
            RateLimit-Remaining:
              description: Requests remaining in the current window.
              schema:
                type: integer
            RateLimit-Reset:
              description: Seconds until the current window resets.
              schema:
                type: integer
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WhoamiResponse:
      properties:
        auth_kind:
          type: string
          enum:
          - apikey
          - jwt
          - shared
          title: Auth Kind
          description: 'How the caller authenticated: ''apikey'' (org API key), ''jwt'' (logged-in user session), or ''shared'' (the shared HAIL_API_KEY, which carries no human identity).'
        organization_id:
          type: string
          format: uuid
          title: Organization Id
          description: Organization the caller belongs to.
        user_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: User Id
          description: The authenticated user's id. Null for 'shared' callers.
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
          description: The authenticated user's email. Null for 'shared' callers.
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: The authenticated user's display name. Null for 'shared' callers.
        superadmin:
          type: boolean
          title: Superadmin
          description: True for a Hail staff console session acting on this organization.
          default: false
      type: object
      required:
      - auth_kind
      - organization_id
      title: WhoamiResponse
      description: 'Who the caller is — the answer ``GET /whoami`` gives.


        ``user_id``/``email``/``name`` are ``None`` for shared-key

        (``HAIL_API_KEY``) callers: that key carries no human identity. An

        agent that wants to put the operator''s address in ``Reply-To`` reads

        ``email`` and skips the header when it is ``None``.'
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
          description: Path to the invalid field within the request, as a list of keys/indices (e.g. ['body', 'to']).
        msg:
          type: string
          title: Message
          description: Human-readable description of the validation failure.
        type:
          type: string
          title: Error Type
          description: Machine-readable error type code (e.g. 'missing', 'string_type').
        input:
          title: Input
          description: The value that was actually provided and failed validation.
        ctx:
          type: object
          title: Context
          description: Additional machine-readable context for the error, when the error type provides one.
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
          description: 'List of validation errors: each entry gives the field location (loc), the problem (msg), and the error type (type).'
      type: object
      title: HTTPValidationError