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

# Search the builder knowledge base

> Search the PolyAI builder knowledge base for design patterns, implementation rules, and best practices. Returns ranked results by relevance. Use this before building or modifying an agent to find the right approach.



## OpenAPI

````yaml api-reference/agents/openapi.json GET /v1/builder-knowledge/search
openapi: 3.1.0
info:
  title: PolyAI Agents API
  version: 1.0.11
  description: Manage PolyAI agents, telephony, deployments, and real-time configs.
servers:
  - url: https://api.us.poly.ai
    description: US region
  - url: https://api.eu.poly.ai
    description: EU region
  - url: https://api.uk.poly.ai
    description: UK region
  - url: https://api.studio.poly.ai
    description: Studio region
security:
  - polyApiKey: []
paths:
  /v1/builder-knowledge/search:
    get:
      tags:
        - Builder Knowledge
      summary: Search the builder knowledge base
      description: >-
        Search the PolyAI builder knowledge base for design patterns,
        implementation rules, and best practices. Returns ranked results by
        relevance. Use this before building or modifying an agent to find the
        right approach.
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
            minLength: 1
          description: Search text, matched against document titles, tags and bodies
        - name: top
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 10
          description: Maximum number of results to return
        - name: category
          in: query
          required: false
          schema:
            type: string
          description: >-
            Only return documents in this knowledge category; GET
            /v1/builder-knowledge/categories lists the valid values
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResponse'
        '400':
          description: Validation error
        '401':
          description: Unauthorized – missing or invalid API key
        '403':
          description: Forbidden – insufficient permissions
components:
  schemas:
    SearchResponse:
      type: object
      title: SearchResponse
      description: Ranked builder knowledge search results.
      properties:
        results:
          type: array
          description: Ranked search results
          items:
            $ref: '#/components/schemas/SearchResultItem'
        total:
          type: integer
          description: Number of results returned
        query:
          type: string
          description: The original search query
      required:
        - results
        - total
        - query
    SearchResultItem:
      type: object
      title: SearchResultItem
      description: A single search hit from the builder knowledge base.
      properties:
        score:
          type: number
          description: BM25 relevance score
        path:
          type: string
          description: Relative path to the document
        title:
          type: string
          description: Document title from frontmatter
        category:
          type: string
          description: Document category
        tags:
          type: array
          description: Document tags from frontmatter
          items:
            type: string
        summary:
          type: string
          description: Short summary of the document
      required:
        - score
        - path
        - title
        - category
        - tags
        - summary
  securitySchemes:
    polyApiKey:
      type: apiKey
      in: header
      name: X-API-KEY

````