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

# Delete a document

> Delete a specific document by ID. You need to create an API Connector to use this endpoint. Head over to the <a href='/admin/connect'>Connectors page</a> to create a new API Connector.

### Rate Limits

600 requests per minute.

These endpoints require a custom API data source. See [Custom API](/admin/data-sources/custom-api) for setup instructions.


## OpenAPI

````yaml /api-reference/openapi.json delete /documents/{data_source_id}/{document_id}
openapi: 3.1.1
info:
  title: Realm API
  version: 0.0.1
  description: |2

      <p>
        Welcome to the Realm API documentation. With this API you can add, edit and delete documents from Realm, as well as integrate Realm into your applications.
      </p>

      <h2>Getting Started</h2>
      <ol>
        <li>First, you'll need to create an API token. You can create your own API token on the <a href="/settings">Settings page</a>, or ask your admin to create one for you on the <a href="/admin/api-access-tokens">Admin API page</a>.
        </li>
        <li>Include your API token in all requests using the Authorization header:
          <pre>Authorization: Bearer [your-api-token]</pre>
        </li>
      </ol>

      <h2>Rate Limits</h2>
      <p>
        This API implements rate limiting using a token bucket algorithm to ensure fair usage and system stability. When rate limits are exceeded, the API will return a 429 Too Many Requests status code.
      </p>
      <p>
        Each endpoint has its own rate limit configuration. If you exceed the rate limit, the request will be queued for up to 3 seconds before being rejected. We recommend implementing exponential backoff in your client applications when receiving 429 responses.
      </p>

      <h2>Pricing</h2>
      <p>
        The API does not have a separate pricing for now; it is included in the Realm subscription. We might change this in the future, but will notice you well in advance if we do.
      </p>

      <h2>Need Help?</h2>
      <p>
        If you encounter any issues or have questions, please contact our team in Slack or via email: <a href="mailto:team@withrealm.com">team@withrealm.com</a>
      </p>
servers:
  - url: https://app.withrealm.com/api/external/alpha
    description: Default multi-tenant environment.
  - url: https://{tenant}.withrealm.com/api/external/alpha
    description: Single-tenant deployment.
    variables:
      tenant:
        default: your-tenant
        description: Your organization's tenant subdomain.
security: []
tags:
  - name: Chats
    description: Endpoints for chat and message management
  - name: Documents
    description: >-
      Endpoints for document management and operations. These endpoints can be
      used with custom connectors - they will not work with pre-built
      connectors. To use these endpoints, you'll need to create a custom
      connector from the <a href='/admin/connect'>Connectors page</a>.
  - name: Connectors
    description: Endpoints for connector management and operations
    x-group: Data sources
  - name: Agents
    description: Endpoints for agent management and operations
paths:
  /documents/{data_source_id}/{document_id}:
    delete:
      tags:
        - Documents
      summary: Delete a document
      description: >-
        Delete a specific document by ID. You need to create an API Connector to
        use this endpoint. Head over to the <a href='/admin/connect'>Connectors
        page</a> to create a new API Connector.


        ### Rate Limits


        600 requests per minute.
      operationId: deleteDocument
      parameters:
        - schema:
            type: string
            description: ID of the custom API data source.
          required: true
          description: ID of the custom API data source.
          in: path
          example: ds_kb_main
          name: data_source_id
        - schema:
            type: string
            description: ID of the document.
          required: true
          description: ID of the document.
          in: path
          example: doc_42
          name: document_id
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteDocumentResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  details:
                    type: string
                required:
                  - error
        '401':
          description: 'Unauthorized: missing or invalid API token'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '403':
          description: >-
            Forbidden: the API token lacks the required scope, or external API
            access is not available on the organization's plan
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '429':
          description: >-
            Too many requests: rate limit exceeded. Retry after the number of
            seconds in the Retry-After response header.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
      security:
        - bearerAuth: []
components:
  schemas:
    DeleteDocumentResponse:
      type: object
      properties:
        success:
          type: boolean
        error:
          type: string
      required:
        - success
      example:
        success: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      x-default: YOUR_API_TOKEN

````