AgentLine Events API

openapi: 3.2.0
info:
  title: Agentline Cloud Events API
  version: 0.3.0
  x-refined-note:
  - x-guidance differs across the merged source definitions and was not carried
  description: 'Operations tagged Events across 2 of this provider''s published API definitions: agentline.cloud_openapi.json, agentline-cloud-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.agentline.cloud
  description: Production
tags:
- name: Events
paths:
  /v1/events:
    get:
      tags:
      - Events
      summary: List Events
      description: 'Poll for telephony events from your AI agents.


        Returns pending events such as call completions, transcripts, and

        failures. Events are consumed on retrieval (one-time read) — once

        polled, they are automatically deleted from the mailbox.


        Your AI agent should call this endpoint periodically to receive

        notifications about completed calls and their transcripts.


        Filters:

        - agent_id: only events for a specific AI agent

        - event_type: e.g. "call.completed", "call.failed"'
      operationId: poll_events
      security:
      - API Key or OAuth: []
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter events by AI agent ID
          title: Agent Id
        description: Filter events by AI agent ID
      - name: event_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter by event type (e.g. 'call.completed', 'call.failed')
          title: Event Type
        description: Filter by event type (e.g. 'call.completed', 'call.failed')
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Maximum number of events to return (1-200)
          default: 50
          title: Limit
        description: Maximum number of events to return (1-200)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - events
      x-fern-sdk-method-name: poll
    servers:
    - url: https://api.agentline.cloud
      description: Production
  /v1/events/peek:
    get:
      tags:
      - Events
      summary: Peek Events
      description: 'Peek at pending telephony events without consuming them.


        Returns a preview of queued events (call completions, transcripts)

        without removing them from the mailbox. Useful for checking if

        there are events to process before committing to retrieve them.'
      operationId: peek_events
      security:
      - API Key or OAuth: []
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter events by AI agent ID
          title: Agent Id
        description: Filter events by AI agent ID
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          description: Maximum number of events to preview (1-200)
          default: 50
          title: Limit
        description: Maximum number of events to preview (1-200)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-fern-sdk-group-name:
      - events
      x-fern-sdk-method-name: peek
    servers:
    - url: https://api.agentline.cloud
      description: Production
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
  securitySchemes:
    API_Key_or_OAuth:
      type: http
      description: 'AgentLine API key. Get one via the email OTP flow (POST /v1/auth/otp then POST /v1/auth/verify). Pass as: Authorization: Bearer al_live_... (legacy sk_live_... still works).'
      scheme: bearer
      bearerFormat: API key (al_live_...)
      x-fern-bearer:
        name: apiKey
        env: AGENTLINE_API_KEY
x-refined-from:
- agentline.cloud_openapi.json
- agentline-cloud-openapi.json