Call2Me Knowledge Base API

openapi: 3.2.0
info:
  title: Call2Me Knowledge Base 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: Knowledge Base
  description: Upload documents (PDF, DOCX, TXT, MD) and URLs to give an agent domain-specific context. Vector search via pgvector + OpenAI embeddings; agents retrieve relevant chunks during conversation to answer factually. Reduces hallucination for product/policy/FAQ Q&A.
  externalDocs:
    description: Learn more about Knowledge Base
    url: https://docs.call2me.app/knowledge-base
paths:
  /v1/knowledge-base/upload:
    post:
      tags:
      - Knowledge Base
      summary: Create Knowledge Base with Files
      description: Create a new knowledge base with text, URL, and file sources.
      operationId: create_knowledge_base_with_files_v1_knowledge_base_upload_post
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_knowledge_base_with_files_v1_knowledge_base_upload_post'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/knowledge-base:
    post:
      tags:
      - Knowledge Base
      summary: Create Knowledge Base
      description: Create a new knowledge base with optional text and URL sources.
      operationId: create_knowledge_base_v1_knowledge_base_post
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKnowledgeBaseRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - Knowledge Base
      summary: List Knowledge Bases
      description: Retrieve all knowledge bases.
      operationId: list_knowledge_bases_v1_knowledge_base_get
      parameters:
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Filter to a specific agent's memories
          title: Agent Id
        description: Filter to a specific agent's memories
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/KnowledgeBase'
                title: Response List Knowledge Bases V1 Knowledge Base Get
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/knowledge-base/{knowledge_base_id}:
    get:
      tags:
      - Knowledge Base
      summary: Get Knowledge Base
      description: Retrieve details of a specific knowledge base.
      operationId: get_knowledge_base_v1_knowledge_base__knowledge_base_id__get
      parameters:
      - name: knowledge_base_id
        in: path
        required: true
        schema:
          type: string
          title: Knowledge Base Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Knowledge Base
      summary: Delete Knowledge Base
      description: Delete a knowledge base and all its sources.
      operationId: delete_knowledge_base_v1_knowledge_base__knowledge_base_id__delete
      parameters:
      - name: knowledge_base_id
        in: path
        required: true
        schema:
          type: string
          title: Knowledge Base Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/knowledge-base/{knowledge_base_id}/add-sources:
    post:
      tags:
      - Knowledge Base
      summary: Add Knowledge Base Sources
      description: Add new sources to an existing knowledge base.
      operationId: add_knowledge_base_sources_v1_knowledge_base__knowledge_base_id__add_sources_post
      parameters:
      - name: knowledge_base_id
        in: path
        required: true
        schema:
          type: string
          title: Knowledge Base Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddKnowledgeBaseSourcesRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/knowledge-base/{knowledge_base_id}/upload:
    post:
      tags:
      - Knowledge Base
      summary: Upload Documents
      description: Upload document files (PDF, DOCX, TXT, MD) to a knowledge base.
      operationId: upload_documents_v1_knowledge_base__knowledge_base_id__upload_post
      parameters:
      - name: knowledge_base_id
        in: path
        required: true
        schema:
          type: string
          title: Knowledge Base Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_documents_v1_knowledge_base__knowledge_base_id__upload_post'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBase'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/knowledge-base/{knowledge_base_id}/source/{source_id}:
    delete:
      tags:
      - Knowledge Base
      summary: Delete Knowledge Base Source
      description: Delete a source from a knowledge base.
      operationId: delete_knowledge_base_source_v1_knowledge_base__knowledge_base_id__source__source_id__delete
      parameters:
      - name: knowledge_base_id
        in: path
        required: true
        schema:
          type: string
          title: Knowledge Base Id
      - name: source_id
        in: path
        required: true
        schema:
          type: string
          title: Source Id
      responses:
        '204':
          description: Successful Response
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/knowledge-base/{knowledge_base_id}/query:
    post:
      tags:
      - Knowledge Base
      summary: Query Knowledge Base
      description: Search knowledge base for relevant content.
      operationId: query_knowledge_base_v1_knowledge_base__knowledge_base_id__query_post
      parameters:
      - name: knowledge_base_id
        in: path
        required: true
        schema:
          type: string
          title: Knowledge Base Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KnowledgeBaseQuery'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseQueryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    KnowledgeBaseStatus:
      type: string
      enum:
      - in_progress
      - complete
      - error
      - refreshing_in_progress
      title: KnowledgeBaseStatus
      description: Status of a knowledge base.
    KnowledgeBaseTextInput:
      properties:
        title:
          type: string
          title: Title
          description: Title of the text
        text:
          type: string
          title: Text
          description: Text content to add
      type: object
      required:
      - title
      - text
      title: KnowledgeBaseTextInput
      description: Text input for creating/adding to knowledge base.
    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
    KnowledgeBaseQuery:
      properties:
        query:
          type: string
          title: Query
          description: Search query
        top_k:
          type: integer
          maximum: 20.0
          minimum: 1.0
          title: Top K
          description: Number of results
          default: 5
        threshold:
          type: number
          maximum: 1.0
          minimum: 0.0
          title: Threshold
          description: Similarity threshold
          default: 0.1
      type: object
      required:
      - query
      title: KnowledgeBaseQuery
      description: Query request for knowledge base.
    KnowledgeBaseSearchResult:
      properties:
        source_id:
          type: string
          title: Source Id
        content:
          type: string
          title: Content
        score:
          type: number
          title: Score
        source_type:
          type: string
          title: Source Type
        title:
          anyOf:
          - type: string
          - type: 'null'
          title: Title
      type: object
      required:
      - source_id
      - content
      - score
      - source_type
      title: KnowledgeBaseSearchResult
      description: Single search result from knowledge base.
    Body_create_knowledge_base_with_files_v1_knowledge_base_upload_post:
      properties:
        knowledge_base_name:
          type: string
          title: Knowledge Base Name
        knowledge_base_texts:
          anyOf:
          - type: string
          - type: 'null'
          title: Knowledge Base Texts
        knowledge_base_urls:
          anyOf:
          - type: string
          - type: 'null'
          title: Knowledge Base Urls
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
        files:
          items:
            type: string
            contentMediaType: application/octet-stream
          type: array
          title: Files
          default: []
      type: object
      required:
      - knowledge_base_name
      title: Body_create_knowledge_base_with_files_v1_knowledge_base_upload_post
    KnowledgeBase:
      properties:
        knowledge_base_id:
          type: string
          title: Knowledge Base Id
          description: Unique identifier
        knowledge_base_name:
          type: string
          maxLength: 40
          title: Knowledge Base Name
          description: Name of the knowledge base
        status:
          $ref: '#/components/schemas/KnowledgeBaseStatus'
          description: Processing status
        knowledge_base_sources:
          items:
            anyOf:
            - $ref: '#/components/schemas/KnowledgeBaseTextSource'
            - $ref: '#/components/schemas/KnowledgeBaseUrlSource'
            - $ref: '#/components/schemas/KnowledgeBaseDocumentSource'
          type: array
          title: Knowledge Base Sources
          description: Sources in this knowledge base
        enable_auto_refresh:
          type: boolean
          title: Enable Auto Refresh
          description: Auto-refresh URLs every 12 hours
          default: false
        last_refreshed_timestamp:
          anyOf:
          - type: integer
          - type: 'null'
          title: Last Refreshed Timestamp
          description: Last refresh timestamp (ms since epoch)
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
          description: Agent this knowledge base is linked to
        chunk_count:
          type: integer
          title: Chunk Count
          description: Number of chunks in this knowledge base
          default: 0
        source_count:
          type: integer
          title: Source Count
          description: Number of sources
          default: 0
        created_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Created At
          description: Creation timestamp
      type: object
      required:
      - knowledge_base_id
      - knowledge_base_name
      - status
      title: KnowledgeBase
      description: Knowledge base response model - matches Retell's schema.
    KnowledgeBaseDocumentSource:
      properties:
        type:
          type: string
          const: document
          title: Type
          default: document
        source_id:
          type: string
          title: Source Id
          description: Unique identifier for this source
        filename:
          type: string
          title: Filename
          description: Original filename
        file_url:
          type: string
          title: File Url
          description: URL to access the file
        file_size:
          type: integer
          title: File Size
          description: File size in bytes
      type: object
      required:
      - source_id
      - filename
      - file_url
      - file_size
      title: KnowledgeBaseDocumentSource
      description: Document/file source in a knowledge base.
    CreateKnowledgeBaseRequest:
      properties:
        knowledge_base_name:
          type: string
          maxLength: 40
          title: Knowledge Base Name
          description: Name of the knowledge base
        knowledge_base_texts:
          anyOf:
          - items:
              $ref: '#/components/schemas/KnowledgeBaseTextInput'
            type: array
          - type: 'null'
          title: Knowledge Base Texts
          description: Texts to add
        knowledge_base_urls:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Knowledge Base Urls
          description: URLs to scrape and add
        enable_auto_refresh:
          type: boolean
          title: Enable Auto Refresh
          description: Auto-refresh URLs every 12 hours
          default: false
        agent_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Agent Id
          description: Agent to own/link this knowledge base to
      type: object
      required:
      - knowledge_base_name
      title: CreateKnowledgeBaseRequest
      description: Request to create a new knowledge base.
    Body_upload_documents_v1_knowledge_base__knowledge_base_id__upload_post:
      properties:
        files:
          items:
            type: string
            contentMediaType: application/octet-stream
          type: array
          title: Files
          description: Document files to upload
      type: object
      required:
      - files
      title: Body_upload_documents_v1_knowledge_base__knowledge_base_id__upload_post
    KnowledgeBaseTextSource:
      properties:
        type:
          type: string
          const: text
          title: Type
          default: text
        source_id:
          type: string
          title: Source Id
          description: Unique identifier for this source
        title:
          type: string
          title: Title
          description: Title of the text content
        content:
          type: string
          title: Content
          description: Text content
      type: object
      required:
      - source_id
      - title
      - content
      title: KnowledgeBaseTextSource
      description: Text source in a knowledge base.
    KnowledgeBaseQueryResponse:
      properties:
        query:
          type: string
          title: Query
        results:
          items:
            $ref: '#/components/schemas/KnowledgeBaseSearchResult'
          type: array
          title: Results
        context_text:
          type: string
          title: Context Text
          description: Formatted context for LLM
      type: object
      required:
      - query
      - results
      - context_text
      title: KnowledgeBaseQueryResponse
      description: Response from knowledge base query.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    KnowledgeBaseUrlSource:
      properties:
        type:
          type: string
          const: url
          title: Type
          default: url
        source_id:
          type: string
          title: Source Id
          description: Unique identifier for this source
        url:
          type: string
          title: Url
          description: URL that was scraped
      type: object
      required:
      - source_id
      - url
      title: KnowledgeBaseUrlSource
      description: URL source in a knowledge base.
    AddKnowledgeBaseSourcesRequest:
      properties:
        knowledge_base_texts:
          anyOf:
          - items:
              $ref: '#/components/schemas/KnowledgeBaseTextInput'
            type: array
          - type: 'null'
          title: Knowledge Base Texts
          description: Texts to add
        knowledge_base_urls:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Knowledge Base Urls
          description: URLs to scrape and add
      type: object
      title: AddKnowledgeBaseSourcesRequest
      description: Request to add sources to an existing knowledge base.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Enter your API key
externalDocs:
  description: Full developer documentation
  url: https://docs.call2me.app