Hail Events API

openapi: 3.2.0
info:
  title: Hail Events 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: Events
paths:
  /v1/events:
    get:
      tags:
      - Events
      summary: List Events
      description: 'Cursor-paginated forward stream of call, email, and SMS events.


        Scoped to the caller''s organization. Pass id (typed ":",

        e.g. "call:") to narrow to one resource''s events, or kind to

        narrow to one event kind. Walks forward in time — pass the returned

        next_cursor to continue tailing where you left off.'
      operationId: list_events_v1_events_get
      parameters:
      - name: cursor
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Cursor
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 1000
          minimum: 1
          default: 100
          title: Limit
      - name: id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Id
      - name: kind
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Kind
      - 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/EventStreamResponse'
        '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:
    EventResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
          description: Unique identifier for this event.
        source:
          type: string
          enum:
          - call
          - email
          - sms
          title: Source
          description: 'Which channel this event belongs to: ''call'', ''email'', or ''sms''.'
        call_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Call Id
          description: The call this event belongs to. Set only when source='call'.
        email_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Email Id
          description: The email this event belongs to. Set only when source='email'.
        sms_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Sms Id
          description: The message this event belongs to. Set only when source='sms'.
        kind:
          type: string
          title: Kind
          description: Event kind within the source (e.g. 'queued', 'delivered', 'bounced'). Vocabulary differs per source.
        payload:
          additionalProperties: true
          type: object
          title: Payload
          description: Event-kind-specific detail, as a free-form JSON object.
        occurred_at:
          type: string
          format: date-time
          title: Occurred At
          description: When this event occurred, ISO 8601 timestamp.
      type: object
      required:
      - id
      - source
      - kind
      - payload
      - occurred_at
      title: EventResponse
      description: One event on the unified GET /events stream (call, email, or SMS).
    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
    EventStreamResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/EventResponse'
          type: array
          title: Items
          description: Events in this page, oldest first.
        next_cursor:
          anyOf:
          - type: string
          - type: 'null'
          title: Next Cursor
          description: Opaque cursor for the next page. Null when there are no more results.
        call_status:
          anyOf:
          - type: string
            enum:
            - queued
            - dialing
            - ringing
            - in_progress
            - completed
            - failed
            - busy
            - no_answer
            - canceled
          - type: 'null'
          title: Call Status
          description: Current status of the call named by the id filter (e.g. id=call:<uuid>). Null for org-wide tails and non-call filters, since there is no single call to report a status for.
      type: object
      required:
      - items
      title: EventStreamResponse
    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