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

# Delete Knowledge Base

> Soft delete one knowledge base.

<span data-api-safety-label="destructive"><Badge color="red" size="sm" shape="pill">Destructive</Badge></span>

<Info>
  **v1 only.** Knowledge bases are available on the `/v1` API. There is no legacy unversioned equivalent.
</Info>

Soft-delete a knowledge base. DialNexa blocks the delete while the knowledge base is still attached to the current draft or latest published version of any agent in the workspace. The delete is reversible by support within the retention window.

## When to use this

* **Retiring content**: remove a knowledge base whose content is obsolete so agents stop answering from it.
* **Multi-tenant offboarding**: delete a per-customer knowledge base when that customer leaves.

Before deleting, check which agents reference the knowledge base and update their `knowledge_base_ids` via [Update Agent](/docs/api-reference/v1/agents/update) if they should switch to a replacement. If any agent still uses the knowledge base, the API returns `409 Conflict` with the affected `agent_ids`. A `404 Not Found` means the knowledge base does not exist in this workspace. See [Errors](/docs/api-reference/errors) for the standard error format.


## OpenAPI

````yaml DELETE /v1/knowledge-base/{id}
openapi: 3.0.0
info:
  title: DialNexa API
  description: >-
    Public REST API for the DialNexa voice AI platform. Versioned endpoints are
    under /v1; unversioned endpoints are legacy and deprecated.
  version: 1.0.0
servers:
  - url: https://api.dialnexa.com
    description: DialNexa production API
security:
  - bearer: []
tags:
  - name: API Keys
  - name: Agent Functions
  - name: Agents V1
  - name: Agents2
  - name: Batch Calls
  - name: Batch Calls V1
  - name: Call Logs
  - name: Calls
  - name: Calls V1
  - name: Campaign Leads
  - name: Campaigns
  - name: External Webhooks
  - name: Knowledge Base
  - name: Knowledge Base V1
  - name: LLMs
  - name: LLMs V1
  - name: Languages
  - name: Languages V1
  - name: Organization Phone Numbers
  - name: Organization Phone Numbers V1
  - name: Phone Number Pricing
  - name: Phone Number Pricing V1
  - name: Transcribers
  - name: Transcribers V1
  - name: User Webhooks
  - name: User Webhooks V1
  - name: V1
  - name: Voices
  - name: Voices V1
  - name: Webcall
  - name: Workflow Leads
  - name: Workflow Leads V1
  - name: Workflows
  - name: Workflows V1
paths:
  /v1/knowledge-base/{id}:
    delete:
      tags:
        - Knowledge Base
        - Knowledge Base V1
        - V1
      summary: Delete Knowledge Base
      description: >-
        Soft-deletes a knowledge base. Deletion is blocked with `409 Conflict`
        while the knowledge base is still referenced by the current draft or
        latest published version of any agent in the workspace.
      operationId: KnowledgeBaseV1Controller_remove
      parameters:
        - name: id
          required: true
          in: path
          schema:
            type: string
      responses:
        '200':
          description: Knowledge base deleted successfully.
          content:
            application/json:
              examples:
                success:
                  summary: Successful response
                  value:
                    success: true
                    message: Knowledge base deleted successfully
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Knowledge base deleted successfully
        '401':
          description: Unauthorized - missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 401 Unauthorized
                  value:
                    statusCode: 401
                    message: API key is missing or invalid
                    error: Unauthorized
        '403':
          description: Forbidden - knowledge base does not belong to your organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 403 Forbidden
                  value:
                    statusCode: 403
                    message: You do not have permission to access this resource
                    error: Forbidden
        '404':
          description: Knowledge base not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 404 Not Found
                  value:
                    statusCode: 404
                    message: Knowledge base not found
                    error: Not Found
        '409':
          description: Knowledge base is still used by one or more agents.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/ErrorResponse'
                properties:
                  agent_ids:
                    type: array
                    items:
                      type: string
                    example:
                      - agent_2g7Xy3tY53gRlp
              examples:
                knowledgeBaseInUse:
                  summary: 409 Conflict
                  value:
                    statusCode: 409
                    message: >-
                      This knowledge base cannot be deleted because it is being
                      used by 1 agent(s): agent_2g7Xy3tY53gRlp. Please unlink it
                      from these agents before deleting.
                    agent_ids:
                      - agent_2g7Xy3tY53gRlp
                    error: Conflict
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                error:
                  summary: 500 Internal Server Error
                  value:
                    statusCode: 500
                    message: Internal server error
                    error: Internal Server Error
      security:
        - bearer: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 400
        message:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          example: phone_number must be a valid E.164 phone number
        error:
          type: string
          example: Bad Request
      required:
        - statusCode
        - message
        - error
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      type: http

````