Call2Me Schedules API

openapi: 3.2.0
info:
  title: Call2Me Schedules 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: Schedules
  description: One-shot or recurring scheduled outbound calls. Use this for follow-ups, reminders, periodic check-ins. Recurrence supports daily/weekly/monthly cron-style rules.
  externalDocs:
    description: Learn more about schedules
    url: https://docs.call2me.app/schedules
paths:
  /v1/schedules:
    post:
      tags:
      - Schedules
      summary: Create Schedule
      description: Create a scheduled call.
      operationId: create_schedule_v1_schedules_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduleRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Schedules
      summary: List Schedules
      description: List scheduled calls.
      operationId: list_schedules_v1_schedules_get
      parameters:
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
      - name: search
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Search
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/schedules/upcoming:
    get:
      tags:
      - Schedules
      summary: Get Upcoming
      description: Get upcoming scheduled calls for the next N days.
      operationId: get_upcoming_v1_schedules_upcoming_get
      parameters:
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 30
          minimum: 1
          default: 7
          title: Days
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/schedules/{schedule_id}:
    get:
      tags:
      - Schedules
      summary: Get Schedule
      description: Get schedule details.
      operationId: get_schedule_v1_schedules__schedule_id__get
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - Schedules
      summary: Update Schedule
      description: Update a scheduled call.
      operationId: update_schedule_v1_schedules__schedule_id__patch
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduleRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Schedules
      summary: Delete Schedule
      description: Delete a scheduled call.
      operationId: delete_schedule_v1_schedules__schedule_id__delete
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/schedules/{schedule_id}/cancel:
    post:
      tags:
      - Schedules
      summary: Cancel Schedule
      description: Cancel a scheduled call.
      operationId: cancel_schedule_v1_schedules__schedule_id__cancel_post
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/schedules/{schedule_id}/approve:
    post:
      tags:
      - Schedules
      summary: Approve Callback
      description: 'Promote a `pending_review` callback request to an actual scheduled call.


        Without scheduled_at → "call now" (cron dials on its next minute run).

        With scheduled_at (future) → scheduled for that time. Either way the cron,

        which only runs status=''scheduled'', will now pick it up.'
      operationId: approve_callback_v1_schedules__schedule_id__approve_post
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApproveCallbackRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/schedules/{schedule_id}/executions:
    get:
      tags:
      - Schedules
      summary: Get Executions
      description: Get execution history for a schedule.
      operationId: get_executions_v1_schedules__schedule_id__executions_get
      parameters:
      - name: schedule_id
        in: path
        required: true
        schema:
          type: string
          title: Schedule Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          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:
    UpdateScheduleRequest:
      properties:
        scheduled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Scheduled At
        timezone:
          anyOf:
          - type: string
          - type: 'null'
          title: Timezone
        contact_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Name
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        variables:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Variables
        recurrence:
          anyOf:
          - type: string
            pattern: ^(daily|weekly|monthly)$
          - type: 'null'
          title: Recurrence
        recurrence_end_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Recurrence End At
      type: object
      title: UpdateScheduleRequest
    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
    ApproveCallbackRequest:
      properties:
        scheduled_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Scheduled At
      type: object
      title: ApproveCallbackRequest
      description: Approve a pending_review callback → turn it into a real scheduled call.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    CreateScheduleRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
        phone_number:
          type: string
          pattern: ^\+[1-9]\d{1,14}$
          title: Phone Number
        from_number:
          anyOf:
          - type: string
          - type: 'null'
          title: From Number
        contact_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Contact Name
        scheduled_at:
          type: string
          format: date-time
          title: Scheduled At
        timezone:
          type: string
          title: Timezone
          default: Europe/Istanbul
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
        variables:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Variables
        recurrence:
          anyOf:
          - type: string
            pattern: ^(daily|weekly|monthly)$
          - type: 'null'
          title: Recurrence
        recurrence_end_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Recurrence End At
      type: object
      required:
      - agent_id
      - phone_number
      - scheduled_at
      title: CreateScheduleRequest
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Enter your API key
externalDocs:
  description: Full developer documentation
  url: https://docs.call2me.app