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

# Add a knowledge base

> Attach it to agents by its id, in their config.knowledgeBaseIds. 409 if the name is taken.



## OpenAPI

````yaml /api-reference/openapi.json post /knowledge-bases
openapi: 3.1.0
info:
  title: Talking Avatar API
  version: '1'
  description: >-
    Your account from your server, with an API key: voice agents, calls,
    knowledge bases, links, usage and billing. Send API-Version: 1 to pin
    version 1.
servers:
  - url: https://backend.talking-avatar.dev/api/talking-avatar
security:
  - apiKey: []
paths:
  /knowledge-bases:
    post:
      summary: Add a knowledge base
      description: >-
        Attach it to agents by its id, in their config.knowledgeBaseIds. 409 if
        the name is taken.
      parameters:
        - name: API-Version
          in: header
          description: 'The API version. Without it: 1.'
          schema:
            type: string
            enum:
              - '1'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  pattern: ^[A-Za-z0-9_-]{1,64}$
                  not:
                    const: end_call
                  description: The function name its agents call it by. One per account.
                instruction:
                  type: string
                  minLength: 1
                  maxLength: 1000
                  description: When its agents should use it
                text:
                  type: string
                  minLength: 1
                  maxLength: 50000
                  description: What its agents answer from
                fileName:
                  type: string
                  maxLength: 255
                  description: The file the text came from, if any (when adding)
              required:
                - name
                - instruction
                - text
              additionalProperties: false
            example:
              name: refund_policy
              instruction: Use this to answer questions about refunds and returns.
              text: >-
                You can return any item within 30 days of delivery for a full
                refund.
      responses:
        '201':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                        description: >-
                          The knowledge base's ID, for an agent's
                          config.knowledgeBaseIds
                      name:
                        type: string
                        description: The function name its agents call it by
                      instruction:
                        type: string
                        description: When its agents use it
                      file_name:
                        type:
                          - string
                          - 'null'
                        description: The file its text came from
                      characters:
                        type: integer
                        description: How long its text is
                      created_at:
                        type: string
                        format: date-time
                      updated_at:
                        type: string
                        format: date-time
                      agents:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: The agent's ID
                            name:
                              type: string
                          required:
                            - id
                            - name
                          additionalProperties: false
                        description: The agents it's attached to
                    required:
                      - id
                      - name
                      - instruction
                      - file_name
                      - characters
                      - created_at
                      - updated_at
                      - agents
                    additionalProperties: false
                  code:
                    type: integer
                    const: 201
                  message:
                    type: string
                required:
                  - data
                  - code
        4XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        5XX:
          description: Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: >-
            curl -X POST
            https://backend.talking-avatar.dev/api/talking-avatar/knowledge-bases
            \
              -H "Authorization: Bearer $TALKING_AVATAR_API_KEY" \
              -H "API-Version: 1" \
              -H "Content-Type: application/json" \
              -d '{
              "name": "refund_policy",
              "instruction": "Use this to answer questions about refunds and returns.",
              "text": "You can return any item within 30 days of delivery for a full refund."
            }'
        - lang: python
          label: Python
          source: |-
            import os, requests

            response = requests.post(
                "https://backend.talking-avatar.dev/api/talking-avatar/knowledge-bases",
                headers={
                    "Authorization": f"Bearer {os.environ['TALKING_AVATAR_API_KEY']}",
                    "API-Version": "1",
                },
                json={
                    "name": "refund_policy",
                    "instruction": "Use this to answer questions about refunds and returns.",
                    "text": "You can return any item within 30 days of delivery for a full refund.",
                },
            )
            response.raise_for_status()
            data = response.json()["data"]
        - lang: javascript
          label: Node.js
          source: >-
            const response = await
            fetch("https://backend.talking-avatar.dev/api/talking-avatar/knowledge-bases",
            {
              method: "POST",
              headers: {
                Authorization: `Bearer ${process.env.TALKING_AVATAR_API_KEY}`,
                "API-Version": "1",
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
                "name": "refund_policy",
                "instruction": "Use this to answer questions about refunds and returns.",
                "text": "You can return any item within 30 days of delivery for a full refund."
              }),
            });

            const { data } = await response.json();
components:
  schemas:
    Error:
      type: object
      properties:
        code:
          type: integer
          description: The HTTP status
        message:
          type: string
          description: What went wrong, readable
        data:
          type: 'null'
      required:
        - code
      additionalProperties: false
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Your API key, tav_…
      x-default: YOUR_API_KEY

````

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