Hail Providers API

openapi: 3.2.0
info:
  title: Hail Providers 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: Providers
paths:
  /v1/providers:
    get:
      tags:
      - Providers
      summary: List Providers
      description: Every saved provider row for the caller's organization, all layers.
      operationId: list_providers
      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/ProviderConfigListResponse'
        '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'
  /v1/providers/{layer}:
    put:
      tags:
      - Providers
      summary: Upsert Provider
      description: 'Save a provider for ``layer`` and make it the active one.


        A partial write: anything you omit keeps its saved value. Omitting

        ``api_key`` keeps the stored key, ``params`` keys you don''t send are

        preserved, and omitting ``fallback_enabled`` leaves the flag alone

        (``false`` on a new row). The merged result — not the partial input —

        is validated against the layer''s schema (422 on a mismatch). 404 on an

        unknown layer.'
      operationId: upsert_provider
      parameters:
      - name: layer
        in: path
        required: true
        schema:
          type: string
          title: Layer
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderConfigUpsert'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfigEntry'
        '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'
  /v1/providers/{layer}/{provider}:
    delete:
      tags:
      - Providers
      summary: Delete Provider
      description: 'Delete one provider row. Deleting the active row promotes the

        most-recently-updated sibling. Idempotent: deleting a row that isn''t

        there is a 204 too. 404 on an unknown layer.'
      operationId: delete_provider
      parameters:
      - name: layer
        in: path
        required: true
        schema:
          type: string
          title: Layer
      - name: provider
        in: path
        required: true
        schema:
          type: string
          title: Provider
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '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'
  /v1/providers/{layer}/activate:
    post:
      tags:
      - Providers
      summary: Activate Provider
      description: 'Switch which saved provider is active for ``layer``. 404 when that

        provider has no saved config.'
      operationId: activate_provider
      parameters:
      - name: layer
        in: path
        required: true
        schema:
          type: string
          title: Layer
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderActivateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderConfigEntry'
        '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'
  /v1/providers/{layer}/validate:
    post:
      tags:
      - Providers
      summary: Validate Provider
      description: 'Probe a provider key against the real provider.


        Empty body tests the layer''s active provider with its stored key; send

        ``provider`` to test a specific saved row, or ``api_key`` (plus

        ``provider``/``params``) to test a key before saving it.'
      operationId: validate_provider
      parameters:
      - name: layer
        in: path
        required: true
        schema:
          type: string
          title: Layer
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProviderValidateRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderValidateResult'
        '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:
    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
    ProviderValidateRequest:
      properties:
        api_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
          description: Key to test instead of the stored one. Not persisted.
        provider:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider
          description: 'Provider to test. Omitted: the layer''s currently active provider.'
        params:
          additionalProperties: true
          type: object
          title: Params
          description: Provider-specific config to test alongside the key.
      additionalProperties: false
      type: object
      title: ProviderValidateRequest
      description: 'Body of ``POST /providers/{layer}/validate`` — a live key probe.


        All fields optional: with an empty body the layer''s active provider and

        its stored key are tested. ``provider`` tests that provider''s stored key

        instead. ``api_key`` tests a key that has not been saved yet.'
    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
    ProviderConfigListResponse:
      properties:
        providers:
          items:
            $ref: '#/components/schemas/ProviderConfigEntry'
          type: array
          title: Providers
          description: Every saved provider row for the organization, across all layers.
      type: object
      required:
      - providers
      title: ProviderConfigListResponse
    ProviderConfigUpsert:
      properties:
        provider:
          type: string
          title: Provider
          description: Provider name to save/activate for this layer (e.g. 'openai', 'cartesia').
        api_key:
          anyOf:
          - type: string
          - type: 'null'
          title: Api Key
          description: API key for this provider. Omit to edit params without resending the key. Write-only — never echoed back.
        params:
          additionalProperties: true
          type: object
          title: Params
          description: Provider-specific config, validated against the layer's schema (LLMParams/TTSParams/STTParams). Only the keys you send are changed; other saved keys are kept.
        fallback_enabled:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Fallback Enabled
          description: Whether to fall back to Hail's default provider on failure. Omit to leave unchanged; defaults to false on a new row.
      additionalProperties: false
      type: object
      required:
      - provider
      title: ProviderConfigUpsert
      description: 'Body of ``PUT /providers/{layer}`` — save and activate one provider.


        A partial write. Fields you omit keep the value already saved for this

        ``(layer, provider)`` pair: omit ``api_key`` to edit params without

        resending the key, send only the ``params`` keys you want to change,

        and omit ``fallback_enabled`` to leave the flag as it is. The merged

        result is what gets validated against the layer''s schema (422 on a

        mismatch), so a partial write can never leave an invalid config behind.


        Rows are keyed by ``(organization, layer, provider)``, so writing a

        *different* provider for the same layer starts from scratch rather than

        inheriting the previous provider''s params. On a brand-new row

        ``fallback_enabled`` defaults to ``false``.


        Keys are write-only: no response ever echoes one back.'
    ProviderValidateResult:
      properties:
        status:
          type: string
          title: Status
          description: 'Probe outcome: ''valid'', ''invalid'', or ''indeterminate'' (the provider could not be reached).'
        message:
          anyOf:
          - type: string
          - type: 'null'
          title: Message
          description: Human-readable detail about the outcome. 'ok' on success, an error description otherwise.
      type: object
      required:
      - status
      - message
      title: ProviderValidateResult
      description: Outcome of a live provider-key probe.
    ProviderConfigEntry:
      properties:
        layer:
          type: string
          enum:
          - llm
          - tts
          - stt
          title: Layer
          description: Voice-pipeline layer this config applies to.
        provider:
          type: string
          title: Provider
          description: Provider name (e.g. 'openai', 'cartesia').
        key_last4:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Last4
          description: Last 4 characters of the saved API key, for display. Null if no key is saved.
        key_set_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Key Set At
          description: When the API key was last set, ISO 8601 timestamp. Null if no key is saved.
        params:
          additionalProperties: true
          type: object
          title: Params
          description: Saved provider-specific config for this row.
        fallback_enabled:
          type: boolean
          title: Fallback Enabled
          description: Whether Hail's default provider is used as a fallback if this one fails.
        is_active:
          type: boolean
          title: Is Active
          description: True if this is the row currently used by calls on this layer.
      type: object
      required:
      - layer
      - provider
      - key_last4
      - key_set_at
      - params
      - fallback_enabled
      - is_active
      title: ProviderConfigEntry
      description: 'One saved provider row. Write-only key: ``key_last4`` and

        ``key_set_at`` are the only key-derived fields that leave the API.


        Every field is required (``key_last4``/``key_set_at`` nullable): the

        serializer always emits all of them, and required response fields

        generate plain values instead of pointers in the Go CLI''s client.'
    ProviderActivateRequest:
      properties:
        provider:
          type: string
          title: Provider
          description: Previously saved provider to make active for this layer.
      additionalProperties: false
      type: object
      required:
      - provider
      title: ProviderActivateRequest
      description: Body of ``POST /providers/{layer}/activate``.