> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Get phone agent knowledge-source tree

> Get phone agent knowledge-source tree — Returns the instructions and knowledge the agent can use, which of them are selected, and how the agent gets them during calls.



## OpenAPI

````yaml get /phone/{phone_agent_id}/knowledge-sources
openapi: 3.1.0
info:
  title: OpenCX API
  description: >

    OpenCX is an AI-powered, all-in-one platform for customer support and
    outbound communications.


    Use this API to manage your OpenCX organization's AI agents, actions,
    conversations, contacts, and more.


    To get started, generate a new API key from the dashboard.


    ## Authentication

    All API endpoints require authentication using a Bearer token. You can
    generate an API key from your OpenCX dashboard.


    ## Rate Limiting

    API requests are rate limited to ensure fair usage. The current limits are:

    - 100 requests per minute for standard endpoints

    - 1000 requests per minute for streaming endpoints


    ## Error Handling

    The API uses standard HTTP status codes and returns detailed error messages
    in the response body.
  version: 1.0-beta
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: http://localhost:8080
    description: Development
  - url: https://api.open.cx
    description: Production
security:
  - bearerAuth: []
paths:
  /phone/{phone_agent_id}/knowledge-sources:
    get:
      summary: Get phone agent knowledge-source tree
      description: >-
        Returns the instructions and knowledge the agent can use, which of them
        are selected, and how the agent gets them during calls. An agent only
        uses what is selected.
      operationId: getPhoneAgentKnowledgeSources
      parameters:
        - schema:
            type: string
          in: path
          name: phone_agent_id
          required: true
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeSourceTreeDto'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorDto'
components:
  schemas:
    KnowledgeSourceTreeDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/KnowledgeSourceTreeDto'
      type: object
      properties:
        directories:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeSourceDirectoryDto'
        uncategorized:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeSourceTreeItemDto'
        totalTokens:
          type: number
          description: >-
            Estimated tokens of the selected instructions and knowledge
            documents
        instructionMode:
          type: string
          enum:
            - all
            - selected
          description: >-
            Deprecated: always selected. The agent only uses the instructions
            selected here.
        knowledgeMode:
          type: string
          enum:
            - all
            - selected
          description: >-
            Deprecated: always selected. The agent only uses the knowledge
            selected here.
        knowledgePlan:
          anyOf:
            - $ref: '#/components/schemas/PhoneAgentKnowledgePlanDto'
            - type: 'null'
          description: >-
            How the agent gets the selected sources during calls; null for
            agents on another runtime
        selectedInstructionIds:
          type: array
          items:
            type: string
        selectedDirectoryIds:
          type: array
          items:
            type: string
        selectedKnowledgeItemIds:
          type: array
          items:
            type: string
        selectedKnowledgeFolderKeys:
          type: array
          items:
            type: string
        routingGuide:
          anyOf:
            - $ref: '#/components/schemas/KnowledgeSourceRoutingGuideDto'
            - type: 'null'
        knowledgeFolders:
          type: array
          items:
            type: object
            properties:
              key:
                type: string
              dataSource:
                type: string
                enum:
                  - confluence
                  - notion
                  - zendesk_support
                  - shopify
                  - gitbook
                  - intercom
                  - front
                  - freshdesk
                  - hubspot_kb
                  - sharepoint
                  - genesys
                  - ai_instructions
                  - custom_training
                  - website
                  - workflow
                  - help_center
              stream:
                type:
                  - string
                  - 'null'
              label:
                type:
                  - string
                  - 'null'
              documentCount:
                type: number
              selected:
                type: boolean
              folder:
                type:
                  - string
                  - 'null'
              parentFolder:
                type:
                  - string
                  - 'null'
              selectable:
                type: boolean
                description: Whether this source can be selected for a voice agent
              unavailableReason:
                description: User-facing explanation when the source cannot be selected
                type:
                  - string
                  - 'null'
            required:
              - key
              - dataSource
              - stream
              - label
              - documentCount
              - selected
              - selectable
              - unavailableReason
            additionalProperties: false
      required:
        - directories
        - uncategorized
        - totalTokens
        - instructionMode
        - knowledgeMode
        - knowledgePlan
        - selectedInstructionIds
        - selectedDirectoryIds
        - selectedKnowledgeItemIds
        - selectedKnowledgeFolderKeys
        - routingGuide
        - knowledgeFolders
      additionalProperties: false
    ErrorDto:
      type: object
      properties:
        statusCode:
          type: integer
        message:
          type: string
        error:
          type: string
    KnowledgeSourceDirectoryDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/KnowledgeSourceDirectoryDto'
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        parent_id:
          description: Parent directory id; null for a top-level directory
          type:
            - string
            - 'null'
        items:
          type: array
          items:
            $ref: '#/components/schemas/KnowledgeSourceTreeItemDto'
        selected:
          type: boolean
          description: >-
            Whether the entire directory is selected (all current and future
            instructions included)
        selectable:
          type: boolean
          description: Whether this source can be selected for a voice agent
        unavailableReason:
          description: User-facing explanation when the source cannot be selected
          type:
            - string
            - 'null'
      required:
        - id
        - name
        - parent_id
        - items
        - selected
        - selectable
        - unavailableReason
      additionalProperties: false
    KnowledgeSourceTreeItemDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/KnowledgeSourceTreeItemDto'
      type: object
      properties:
        id:
          type: string
        question:
          type: string
          description: The scenario/title of the instruction
        answer:
          type: string
          description: The content of the instruction
        directory_id:
          type:
            - string
            - 'null'
        selected:
          type: boolean
          description: Whether this instruction is individually selected
        selectable:
          type: boolean
          description: Whether this source can be selected for a voice agent
        unavailableReason:
          description: User-facing explanation when the source cannot be selected
          type:
            - string
            - 'null'
      required:
        - id
        - question
        - answer
        - directory_id
        - selected
        - selectable
        - unavailableReason
      additionalProperties: false
    PhoneAgentKnowledgePlanDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/PhoneAgentKnowledgePlanDto'
      type: object
      properties:
        mode:
          type: string
          enum:
            - none
            - preload
            - search
          description: >-
            How a save now would give the agent its selection. none: nothing is
            selected, so the agent only follows its own instructions. preload:
            every selected source is loaded at the start of each call. search:
            the selection is too large to load, so the agent searches it during
            calls.
        searchEnabled:
          type: boolean
          description: >-
            Whether the agent searches during calls now. Set when the agent is
            saved; differs from mode when the selected sources changed size
            since.
        selectedSourceCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: >-
            Selected instructions and knowledge documents currently available to
            voice calls
        capacityUsedPercent:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          description: >-
            Share of the room for loading sources at call start that the agent's
            instructions and selection would use. Above 100, the agent searches
            instead.
      required:
        - mode
        - searchEnabled
        - selectedSourceCount
        - capacityUsedPercent
      additionalProperties: false
    KnowledgeSourceRoutingGuideDto:
      $schema: https://json-schema.org/draft/2020-12/schema
      $id: '#/components/schemas/KnowledgeSourceRoutingGuideDto'
      type: object
      properties:
        status:
          type: string
          enum:
            - fresh
            - stale
            - invalid
        generatedAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
        generationDurationMs:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        schemaVersion:
          type: integer
          exclusiveMinimum: 0
          maximum: 9007199254740991
        sourceCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        concepts:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              kind:
                type: string
                enum:
                  - audience
                  - product
                  - intent_family
                  - state_axis
                  - vocabulary
              label:
                type: string
              description:
                type: string
              aliases:
                type: array
                items:
                  type: string
              sourceCount:
                type: integer
                exclusiveMinimum: 0
                maximum: 9007199254740991
              confidence:
                type: number
                minimum: 0
                maximum: 1
            required:
              - id
              - kind
              - label
              - description
              - aliases
              - sourceCount
              - confidence
            additionalProperties: false
        distinctions:
          type: array
          items:
            type: object
            properties:
              conceptIds:
                type: array
                items:
                  type: string
              relationship:
                type: string
                enum:
                  - confusable
                  - overlapping
                  - narrower_broader
                  - complementary
                  - mutually_exclusive
              distinction:
                type: string
              clarifyingQuestion:
                type:
                  - string
                  - 'null'
              confidence:
                type: number
                minimum: 0
                maximum: 1
            required:
              - conceptIds
              - relationship
              - distinction
              - clarifyingQuestion
              - confidence
            additionalProperties: false
        toolTransitions:
          type: array
          items:
            type: object
            properties:
              toolName:
                type: string
              outcomeFields:
                type: array
                items:
                  type: string
              conditions:
                type: array
                items:
                  type: object
                  properties:
                    field:
                      type: string
                    operator:
                      type: string
                      enum:
                        - equals
                        - not_equals
                        - one_of
                        - present
                        - absent
                        - truthy
                        - falsy
                    values:
                      type: array
                      items:
                        type: string
                  required:
                    - field
                    - operator
                    - values
                  additionalProperties: false
              searchIntent:
                type: string
              confidence:
                type: number
                minimum: 0
                maximum: 1
            required:
              - toolName
              - outcomeFields
              - conditions
              - searchIntent
              - confidence
            additionalProperties: false
        changeSet:
          type: object
          properties:
            addedConceptIds:
              type: array
              items:
                type: string
            updatedConceptIds:
              type: array
              items:
                type: string
            removedConceptIds:
              type: array
              items:
                type: string
          required:
            - addedConceptIds
            - updatedConceptIds
            - removedConceptIds
          additionalProperties: false
      required:
        - status
        - generatedAt
        - generationDurationMs
        - schemaVersion
        - sourceCount
        - concepts
        - distinctions
        - toolTransitions
        - changeSet
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.