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

# Create knowledge base entry

> Creates one knowledge base text entry. `description_category` defaults to `company_information` when omitted, so a minimal `{ name, content }` body succeeds; a `custom` category requires a non-empty `custom_description`. Entry names are unique within the account. Requires scope: `knowledge_base:write`.



## OpenAPI

````yaml /api-reference/openapi.json post /v1/knowledge-bases
openapi: 3.0.3
info:
  title: TopCalls Voice API
  description: >
    TopCalls Voice Gateway API for creating and managing AI-powered phone calls.


    ## Authentication


    All API requests require authentication. Include your API key in the
    `Authorization` header:


    ```

    Authorization: Bearer tc_live_xxxxx

    ```


    ## Rate Limits


    Direct call creation via `POST /v1/calls` is limited to your account's

    `max_calls_per_minute` setting (default: 20) per minute. Exceeding it
    returns

    `429 Too Many Requests` with a `Retry-After` header.

    All endpoints are additionally subject to a flat limit of 120 requests per

    minute per account (all methods).


    On a `429`, wait for the number of seconds in the `Retry-After` header, then

    retry the same request. For automated clients, back off progressively on

    repeated `429`s. Limits are per account and are shared by all API keys.


    ## Error Format


    All errors follow RFC 7807 Problem+JSON format:


    ```json

    {
      "type": "https://api.topcalls.ai/errors/insufficient_quota",
      "title": "Insufficient Quota",
      "status": 402,
      "detail": "You need 5 minutes but have 3.5 remaining"
    }

    ```
  version: 1.0.0
  contact:
    name: TopCalls Support
    url: https://topcalls.ai
  license:
    name: Proprietary
servers:
  - url: https://api.topcalls.ai
    description: Production
security: []
tags:
  - name: Calls
    description: Create and manage phone calls
  - name: Phone Numbers
    description: Manage phone numbers and carriers
  - name: Account
    description: Account information and usage
  - name: Webhooks
    description: Webhook configuration and events
  - name: Configuration
    description: Available AI models, voices, and platform capabilities
paths:
  /v1/knowledge-bases:
    post:
      summary: Create knowledge base entry
      description: >-
        Creates one knowledge base text entry. `description_category` defaults
        to `company_information` when omitted, so a minimal `{ name, content }`
        body succeeds; a `custom` category requires a non-empty
        `custom_description`. Entry names are unique within the account.
        Requires scope: `knowledge_base:write`.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKeyHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateKnowledgeBaseEntry'
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KnowledgeBaseEntry'
        '400':
          description: Invalid input
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '409':
          description: >-
            Duplicate entry name, or a request with the same Idempotency-Key is
            in-flight
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '429':
          description: Rate limit exceeded
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
        '500':
          description: Internal error
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Problem'
      security:
        - bearerAuth: []
components:
  parameters:
    IdempotencyKeyHeader:
      name: Idempotency-Key
      in: header
      required: false
      description: |
        Optional client-supplied idempotency key. When present, the gateway
        caches the response for 24 hours and returns the same response on
        retried requests with the same key (account-scoped). Safe for
        retries on network blips. Format: 8-255 ASCII characters from
        `[A-Za-z0-9_-]`.
      schema:
        type: string
        minLength: 8
        maxLength: 255
        pattern: ^[A-Za-z0-9_-]+$
        example: a1b2c3d4-e5f6-7890-abcd-ef0123456789
  schemas:
    CreateKnowledgeBaseEntry:
      type: object
      required:
        - name
        - content
      additionalProperties: false
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        content:
          type: string
          minLength: 50
          maxLength: 10000
        description_category:
          $ref: '#/components/schemas/KnowledgeDescriptionCategory'
        custom_description:
          type: string
          minLength: 1
          maxLength: 100
          description: Required when description_category is custom.
    KnowledgeBaseEntry:
      type: object
      required:
        - id
        - account_id
        - name
        - description_category
        - custom_description
        - content
        - status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          format: uuid
        account_id:
          type: string
          format: uuid
        name:
          type: string
        description_category:
          $ref: '#/components/schemas/KnowledgeDescriptionCategory'
        custom_description:
          type: string
          nullable: true
        content:
          type: string
        status:
          type: string
          description: Processing status. Entries are usable once they carry content.
          enum:
            - draft
            - processing
            - active
            - failed
            - archived
            - updating
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Problem:
      type: object
      required:
        - status
        - title
      properties:
        type:
          type: string
          format: uri
          description: Error type URI
        title:
          type: string
          description: Error title
        status:
          type: integer
          description: HTTP status code
        detail:
          type: string
          description: Human-readable error detail
        code:
          type: string
          description: >
            Machine-readable error code for programmatic handling. Present on

            errors that carry a stable identifier (e.g. `PROMPT_SAFETY_FRAUD`,

            `job_not_found`, `too_many_ids`, `no_matches`). Distinct from the

            per-field `errors[].code` used for validation failures. Scenario-

            specific — see each endpoint's response examples for the exact
            value.
        instance:
          type: string
          format: uuid
          description: Request instance ID
        errors:
          type: array
          description: Validation errors (for 400 responses)
          items:
            type: object
            properties:
              path:
                type: string
                description: Field path (e.g., "phone_number", "metadata.from_number")
              message:
                type: string
                description: Error message
              code:
                type: string
                description: Error code (e.g., "invalid_string", "custom")
        details:
          type: string
          description: Additional error details (for provider errors)
    KnowledgeDescriptionCategory:
      type: string
      description: >-
        Category label for a knowledge base entry. Use `custom` with a
        `custom_description` for a free-form label.
      enum:
        - company_information
        - product_catalog
        - service_offerings
        - restaurant_menu
        - cocktail_bar_menu
        - real_estate_properties
        - faq_support
        - pricing_packages
        - policies_procedures
        - contact_information
        - custom
        - residential_properties
        - commercial_properties
        - luxury_properties
        - property_features
        - food_menu
        - bar_cocktails
        - restaurant_location
        - restaurant_hours
        - restaurant_events
        - business_header
        - real_estate_header
        - restaurant_header
        - products_services_header
        - support_header
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        Use `Authorization: Bearer tc_live_xxxxx`

````