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

# Search Knowledge Nodes

> Search for knowledge base nodes by title, content, or other attributes.



## OpenAPI

````yaml POST /v1/kb/nodes/search
openapi: 3.0.0
info:
  title: Conduit API
  version: 1.0.0
  description: Public API for Conduit.
servers:
  - url: https://api.conduit.ai
    description: Production
security: []
tags:
  - name: meta
    description: Discovery and API metadata endpoints.
  - name: agents
    description: >-
      V2 chat agent configuration, including instructions, skills, triggers, and
      automation behavior.
  - name: contacts
    description: >-
      Contact profile and contact-scoped related resources such as tickets and
      calls.
  - name: workspaces
    description: Workspaces accessible to the current API token.
  - name: escalations
    description: >-
      Chat escalations that require operator review, including message, proposed
      response, and disposition context when available.
  - name: conversations
    description: >-
      Canonical message threads. Use these endpoints to list threads, inspect
      conversation state, read transcripts, and send replies.
  - name: conversation-tags
    description: >-
      Conversation labels, root topics, and subtopics used for classification
      and topic analytics.
  - name: tickets
    description: >-
      Operational queue items tied to conversations, including ticket-scoped
      transcripts and replies.
  - name: calls
    description: Phone call records, transcripts, summaries, and recordings when available.
  - name: reservations
    description: >-
      PMS reservations synced from the workspace's integrations (Hostaway,
      Guesty, Airbnb, etc.), including guest identity, payment status, and stay
      dates.
  - name: appointments
    description: >-
      Scheduled appointments (bookings) backed by the Conduit booking service.
      Exposes allocation context and the upstream booking-service `external_id`.
  - name: helpdesk_tickets
    description: >-
      Helpdesk tickets mirrored from external helpdesk integrations (Zendesk,
      Pylon, Plain), including requester identity and upstream metadata.
  - name: kb
    description: >-
      Knowledge base search and node management. Nodes represent knowledge base
      entries (files or directories), chunks are the indexed retrieval units
      used by search.
  - name: skills
    description: >-
      Workspace agent skills that can be attached to V2 chat agents.
      Sidebar/global-assistant skills are intentionally excluded.
  - name: custom_tools
    description: >-
      Custom code tools: user-authored Python/JavaScript functions executed in a
      sandbox when an agent calls them. Includes a runtimes endpoint describing
      the entrypoint signature, return shape, and available dependencies per
      language.
  - name: inbox_types
    description: >-
      Workspace inbox types. Each id is stable and usable as a message trigger's
      `inboxTypeId` and as the `inbox_type_id` filter on list conversations.
paths:
  /v1/kb/nodes/search:
    post:
      tags:
        - kb
      summary: Search knowledge nodes
      description: >-
        Paginated, filtered listing of knowledge nodes. Supports cursor-based
        keyset pagination and optional body inclusion.
      operationId: searchKnowledgeNodes
      parameters:
        - schema:
            type: string
            description: Workspace to query.
            example: j57demo8f8x7c9v0n2q4r6t8y1u3i5o
          required: true
          name: workspace_id
          in: query
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                filters:
                  type: object
                  properties:
                    entity_ids:
                      type: array
                      items:
                        type: string
                      description: Restrict to nodes scoped to any of these entities.
                    source:
                      type: string
                      enum:
                        - google_drive
                        - notion
                        - airtable
                        - link
                        - pms
                        - ingest
                        - manual
                      description: >-
                        Filter by ingest source. `manual` for nodes created via
                        the API, `pms` for nodes synced from a PMS, `ingest` for
                        file uploads.
                    source_type:
                      type: string
                      enum:
                        - pdf
                        - csv
                        - excel
                        - docx
                        - text
                        - html
                      description: >-
                        Filter by source format (e.g. `pdf`, `link`, `manual`,
                        `notion`).
                    source_id:
                      type: string
                      description: >-
                        Filter by upstream source identifier (e.g. PMS listing
                        id, document hash).
                    is_directory:
                      type: boolean
                      description: '`true` returns only folders, `false` only content nodes.'
                    enabled:
                      type: boolean
                      description: Filter by agent-visibility state.
                    parent_id:
                      type: string
                      description: >-
                        Restrict to direct children of this node. Omit to search
                        across the whole workspace.
                  additionalProperties: false
                pagination:
                  type: object
                  properties:
                    cursor:
                      type: string
                    page_size:
                      type: integer
                      minimum: 1
                      maximum: 100
                      description: Defaults to 20. Max 100.
                  additionalProperties: false
                include_body:
                  type: boolean
                  description: >-
                    Include full node bodies in the response. Off by default to
                    keep payloads small.
              additionalProperties: false
              example:
                filters:
                  parent_id: 65f1a2b3c4d5e6f7a8b9c0d1
                  source: manual
                  enabled: true
                pagination:
                  page_size: 20
                include_body: false
      responses:
        '200':
          description: Knowledge nodes
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        workspace_id:
                          type: string
                        title:
                          type: string
                        body:
                          type: string
                        chunk_body:
                          type: boolean
                          description: >-
                            True when the body is chunked and embedded for
                            search.
                        entity_ids:
                          type: array
                          items:
                            type: string
                        parent_id:
                          type: string
                          nullable: true
                        ancestors:
                          type: array
                          items:
                            type: string
                          description: >-
                            Ordered ancestor node ids from root to immediate
                            parent.
                        depth:
                          type: number
                          description: Depth in the tree, 0 = root.
                        source:
                          type: string
                          enum:
                            - google_drive
                            - notion
                            - airtable
                            - link
                            - pms
                            - ingest
                            - manual
                        source_type:
                          type: string
                          nullable: true
                          enum:
                            - pdf
                            - csv
                            - excel
                            - docx
                            - text
                            - html
                        source_id:
                          type: string
                          nullable: true
                        is_directory:
                          type: boolean
                          description: True for folder nodes that group children.
                        metadata:
                          type: object
                          nullable: true
                          additionalProperties:
                            nullable: true
                        enabled:
                          type: boolean
                        created_by:
                          type: string
                          nullable: true
                        embed_status:
                          type: string
                          nullable: true
                          description: Embedding pipeline state (pending, ready, failed).
                        chunk_count:
                          type: number
                          nullable: true
                        version:
                          type: number
                        tags:
                          type: array
                          items:
                            type: string
                        created_at:
                          type: string
                        updated_at:
                          type: string
                      required:
                        - id
                        - workspace_id
                        - title
                        - body
                        - chunk_body
                        - entity_ids
                        - parent_id
                        - ancestors
                        - depth
                        - source
                        - source_type
                        - source_id
                        - is_directory
                        - metadata
                        - enabled
                        - created_by
                        - embed_status
                        - chunk_count
                        - version
                        - tags
                        - created_at
                        - updated_at
                  next_cursor:
                    type: string
                    nullable: true
                  has_more:
                    type: boolean
                  total_count:
                    type: number
                required:
                  - data
                  - next_cursor
                  - has_more
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '404':
          description: Not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '500':
          description: Internal error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
        '503':
          description: Knowledge service temporarily unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                description: Standard error response.
                example:
                  error: Invalid workspace id
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Token
      description: >-
        Conduit API token. Use `Authorization: Bearer <token>`. Read/write
        endpoints require a token with write access.

````