> ## 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 documents older than a specified timestamp

> Delete documents older than a specified timestamp. This endpoint requires a Data Source ID. To get started:

1. Go to the <a href='/admin/connect'>API Connectors page</a>
2. Create a new API Connector
3. Copy the data source ID from the connector details page
4. Use this ID in the {data_source_id} path parameter

### 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}
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}:
    delete:
      tags:
        - Documents
      summary: Delete documents older than a specified timestamp
      description: >-
        Delete documents older than a specified timestamp. This endpoint
        requires a Data Source ID. To get started:


        1. Go to the <a href='/admin/connect'>API Connectors page</a>

        2. Create a new API Connector

        3. Copy the data source ID from the connector details page

        4. Use this ID in the {data_source_id} path parameter


        ### Rate Limits


        600 requests per minute.
      operationId: deleteDocumentsOlderThan
      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
            format: date-time
            description: >-
              Delete documents whose updatedAt is older than this ISO 8601
              timestamp.
          required: true
          description: >-
            Delete documents whose updatedAt is older than this ISO 8601
            timestamp.
          in: query
          example: '2024-03-20T10:00:00Z'
          name: older_than
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteOlderThanResponse'
        '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:
    DeleteOlderThanResponse:
      type: object
      properties:
        success:
          type: boolean
        message:
          type: string
        details:
          type: object
          properties:
            data_source_id:
              type: string
            older_than:
              type: string
            deleted_count:
              type: number
          required:
            - data_source_id
            - older_than
            - deleted_count
        error:
          type: string
      required:
        - success
        - message
      example:
        success: true
        message: >-
          Deletion started successfully. Documents will be deleted
          asynchronously.
        details:
          data_source_id: ds_kb_main
          older_than: '2024-03-20T10:00:00Z'
          deleted_count: 12
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      x-default: YOUR_API_TOKEN

````