Call2Me Events API

openapi: 3.2.0
info:
  title: Call2Me Events API
  description: '# Call2Me Voice AI Platform API


    Programmatic interface to build, deploy and operate voice AI agents that can place

    and receive phone calls in real time. Designed to be consumed by humans **and** by

    AI agent frameworks (function-calling LLMs, MCP servers, automation platforms like

    Composio, Pipedream, Zapier, n8n).


    ## What you can do


    - **Place outbound calls** — give an agent a phone number to dial; the AI handles

    the conversation end-to-end and returns a transcript + recording.

    - **Manage AI agents** — create personalities, attach voices, system prompts,

    knowledge bases and post-call actions.

    - **Schedule calls** — one-shot or recurring (cron-like) outbound calls.

    - **Knowledge base (RAG)** — upload documents/URLs so the agent answers from your

    data with reduced hallucination.

    - **Inbound** — provision phone numbers that route to your agents.


    ## Common LLM tool-calling use cases


    | Goal | Endpoint |

    |------|----------|

    | "Call this person and read them this script" | `POST /v1/calls` |

    | "Schedule a follow-up tomorrow at 14:00" | `POST /v1/schedules` |

    | "Get the transcript of last call" | `GET /v1/calls/{id}` |

    | "Add this PDF to the agent''s brain" | `POST /v1/knowledge-base/{id}/sources` |


    ## Authentication


    Every request requires a Bearer token issued from the dashboard:


    ```

    Authorization: Bearer c2m_sk_xxxxxxxxxxxxxxxx

    ```


    Get your API key from the API Keys page.

    Keys are scoped per-workspace and can be rotated/revoked any time.


    ## Rate Limits


    | Plan | Requests/min | Concurrent Calls |

    |------|-------------|------------------|

    | Free | 60 | 1 |

    | Pro | 600 | 10 |

    | Enterprise | Unlimited | Unlimited |


    ## SDKs & Integrations


    - Python SDK

    - Node.js SDK

    - OpenAPI 3.1 spec: `/openapi.json` (use it to generate clients or register the

    service with AI tool platforms)


    ## Support


    - Email: support@call2me.app

    - Docs: https://docs.call2me.app

    - Discord: https://discord.gg/call2me'
  version: 1.0.0
  x-logo:
    url: https://call2me.app/logo.png
    altText: Call2Me Logo
  contact:
    name: Call2Me Support
    url: https://call2me.app/support
    email: support@call2me.app
  license:
    name: Commercial — see Terms of Service
    url: https://call2me.app/terms
  termsOfService: https://call2me.app/terms
servers:
- url: https://api.call2me.app
  description: Production
- url: http://localhost:8000
  description: Local Development
security:
- BearerAuth: []
tags:
- name: Events
paths:
  /v1/events:
    post:
      tags:
      - Events
      summary: Ingest Event
      description: Record one event. Always returns 202 — the caller should not retry.
      operationId: ingest_event_v1_events_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncomingEvent'
      responses:
        '202':
          description: Successful Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Ingest Event V1 Events Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Events
      summary: List Events
      description: 'Admin query over event_archive — only critical/error kept there.


        This endpoint is under the public ``/v1/events`` prefix (because POST

        ingest has to be public), so auth enforcement lives in the handler

        itself. It accepts a standard ``Authorization: Bearer `` header.'
      operationId: list_events_v1_events_get
      parameters:
      - name: severity
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 16
          - type: 'null'
          title: Severity
      - name: type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Type
      - name: fingerprint
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Fingerprint
      - name: hours
        in: query
        required: false
        schema:
          type: integer
          maximum: 720
          minimum: 1
          default: 24
          title: Hours
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 500
          minimum: 1
          default: 50
          title: Limit
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
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
    IncomingEvent:
      properties:
        type:
          type: string
          maxLength: 64
          minLength: 1
          title: Type
        source:
          type: string
          maxLength: 32
          minLength: 1
          title: Source
        message:
          type: string
          maxLength: 2000
          minLength: 1
          title: Message
        severity:
          anyOf:
          - type: string
            maxLength: 16
          - type: 'null'
          title: Severity
        tenant:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: Tenant
        session_id:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Session Id
        fingerprint:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Fingerprint
        meta:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Meta
      type: object
      required:
      - type
      - source
      - message
      title: IncomingEvent
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Enter your API key
externalDocs:
  description: Full developer documentation
  url: https://docs.call2me.app