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

# Delete a File

> Remove a file resource, its stored blob, and any indexed vectors.

## Overview

Permanently delete a file resource along with its stored binary, metadata, and all derived vector embeddings. This immediately removes the file's content from search results and retrieval operations.

<Warning>
  **Irreversible**: Deletion cannot be undone. The file, its storage blob, and all vector embeddings are permanently removed.
</Warning>

<Info>
  **Use cases**: Removing outdated documentation, retracting superseded content, managing storage costs, or complying with data deletion requests.
</Info>

## Authentication

Requires valid JWT token or session authentication. You must own the parent corpus.

## Path Parameters

<ParamField path="id" type="UUID" required>
  File resource identifier. Must belong to a corpus you own.

  **Example**: `0f75c73e-91bb-4e2b-9ff2-6820a8636ad8`
</ParamField>

## Example request

```bash theme={null}
curl -X DELETE https://{your-host}/api/data/files/0f75c73e-91bb-4e2b-9ff2-6820a8636ad8/ \
  -H "Authorization: Bearer $SOAR_LABS_TOKEN"
```

## Response Codes

<ResponseField name="204" type="No Content">
  File successfully deleted. No response body returned.
</ResponseField>

<ResponseField name="404" type="Not Found">
  File does not exist or belongs to a corpus you don't own.
</ResponseField>

<ResponseField name="409" type="Conflict">
  Backend could not delete the storage blob or vector embeddings. Retry usually succeeds once the storage subsystem catches up.

  **Common causes:**

  * Storage service temporarily unavailable
  * Vector database connection timeout
  * Concurrent deletion attempt
</ResponseField>

## What Gets Deleted

* **File record** - Database entry with metadata
* **Storage blob** - Actual file binary in cloud/local storage
* **Vector embeddings** - All chunks removed from Qdrant
* **Indexing metadata** - Processing status and timestamps

<Note>
  **Immediate effect**: Deletion prevents the file from appearing in future retrievals. Vector embeddings are removed before the database record is deleted.
</Note>

## Common Use Cases

<AccordionGroup>
  <Accordion title="Verify Before Deletion" icon="shield-check">
    Check file details before permanently deleting:

    ```python theme={null}
    # Get file info first
    file = requests.get(
        f"{base_url}/api/data/files/{file_id}/",
        headers=headers
    ).json()

    print(f"File: {file['metadata'].get('filename', 'Unknown')}")
    print(f"Size: {file['file_size'] / 1024:.2f} KB")
    print(f"Uploaded: {file['created_at']}")
    print(f"Status: {file['indexing_status']}")

    # Confirm deletion
    if input("Delete this file? (yes/no): ") == "yes":
        response = requests.delete(
            f"{base_url}/api/data/files/{file_id}/",
            headers=headers
        )
        if response.status_code == 204:
            print("File deleted successfully")
    ```
  </Accordion>

  <Accordion title="Batch File Deletion" icon="list">
    Remove multiple files efficiently:

    ```python theme={null}
    # Get all files in corpus
    files = requests.get(
        f"{base_url}/api/data/files/?corpora={corpus_id}",
        headers=headers
    ).json()

    # Delete files matching criteria
    deleted_count = 0
    for file in files["results"]:
        # Example: Delete old files
        if should_delete(file):  # Your custom logic
            try:
                response = requests.delete(
                    f"{base_url}/api/data/files/{file['id']}/",
                    headers=headers
                )
                if response.status_code == 204:
                    deleted_count += 1
                    print(f"Deleted: {file['metadata'].get('filename')}")
            except Exception as e:
                print(f"Failed: {e}")

    print(f"Total deleted: {deleted_count}")
    ```
  </Accordion>

  <Accordion title="Replace Updated Content" icon="arrows-rotate">
    Remove old version before uploading new:

    ```python theme={null}
    # Step 1: Delete old file
    requests.delete(
        f"{base_url}/api/data/files/{old_file_id}/",
        headers=headers
    )

    # Step 2: Upload new version
    with open("updated_document.pdf", "rb") as f:
        files = {"files": ("updated_document.pdf", f, "application/pdf")}
        data = {"corpora": corpus_id}

        response = requests.post(
            f"{base_url}/api/data/files/",
            headers={"Authorization": f"Bearer {token}"},
            files=files,
            data=data
        )

    new_file = response.json()[0]
    print(f"New file ID: {new_file['id']}")
    ```

    <Tip>
      **Best practice**: Track file versions by naming convention or metadata to easily identify and replace outdated content.
    </Tip>
  </Accordion>

  <Accordion title="Handle Deletion Failures" icon="triangle-exclamation">
    Implement retry logic for 409 errors:

    ```python theme={null}
    import time

    def safe_delete_file(base_url, headers, file_id, max_retries=3):
        """Delete file with retry logic."""
        for attempt in range(max_retries):
            try:
                response = requests.delete(
                    f"{base_url}/api/data/files/{file_id}/",
                    headers=headers,
                    timeout=60
                )

                if response.status_code == 204:
                    return True
                elif response.status_code == 409:
                    if attempt < max_retries - 1:
                        wait_time = 2 ** attempt
                        print(f"Conflict. Retrying in {wait_time}s...")
                        time.sleep(wait_time)
                    else:
                        print("Deletion failed after retries")
                        return False
                elif response.status_code == 404:
                    print("File not found or already deleted")
                    return False
                else:
                    response.raise_for_status()

            except Exception as e:
                print(f"Error: {e}")
                if attempt < max_retries - 1:
                    time.sleep(2 ** attempt)

        return False
    ```
  </Accordion>

  <Accordion title="Alternative: Move to Archive Corpus" icon="archive">
    Instead of deleting, move files to an archive corpus:

    ```python theme={null}
    # Step 1: Download file metadata
    file = requests.get(
        f"{base_url}/api/data/files/{file_id}/",
        headers=headers
    ).json()

    # Step 2: Download the file blob
    # (Assuming you have a file download endpoint)

    # Step 3: Re-upload to archive corpus
    with open(local_path, "rb") as f:
        files = {"files": (filename, f, content_type)}
        data = {"corpora": archive_corpus_id}

        requests.post(
            f"{base_url}/api/data/files/",
            headers={"Authorization": f"Bearer {token}"},
            files=files,
            data=data
        )

    # Step 4: Delete from original corpus
    requests.delete(
        f"{base_url}/api/data/files/{file_id}/",
        headers=headers
    )

    print("File archived successfully")
    ```

    **Benefits:**

    * Preserves data for potential future use
    * Maintains audit trail
    * Can restore if needed
  </Accordion>
</AccordionGroup>

<Tip>
  **Storage optimization**: Regular cleanup of obsolete files reduces storage costs and improves corpus query performance.
</Tip>

## Client examples

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    import os
    import requests

    BASE_URL = "https://your-soar-instance.com"
    TOKEN = os.environ["SOAR_LABS_TOKEN"]
    FILE_ID = "0f75c73e-91bb-4e2b-9ff2-6820a8636ad8"

    response = requests.delete(
        f"{BASE_URL}/api/data/files/{FILE_ID}/",
        headers={"Authorization": f"Bearer {TOKEN}"},
        timeout=30,
    )
    if response.status_code != 204:
        response.raise_for_status()
    ```
  </Tab>

  <Tab title="TypeScript / JavaScript">
    ```ts theme={null}
    const BASE_URL = "https://your-soar-instance.com";
    const token = process.env.SOAR_LABS_TOKEN!;

    async function deleteFile(fileId: string) {
      const response = await fetch(`${BASE_URL}/api/data/files/${fileId}/`, {
        method: "DELETE",
        headers: {
          Authorization: `Bearer ${token}`,
        },
      });

      if (response.status !== 204) {
        throw new Error(`Delete file failed: ${response.status}`);
      }
    }
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    import java.net.URI;
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;

    var BASE_URL = "https://your-soar-instance.com";
    var token = System.getenv("SOAR_LABS_TOKEN");
    var fileId = "0f75c73e-91bb-4e2b-9ff2-6820a8636ad8";

    var request = HttpRequest.newBuilder(URI.create(BASE_URL + "/api/data/files/" + fileId + "/"))
        .header("Authorization", "Bearer " + token)
        .DELETE()
        .build();

    var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.discarding());

    if (response.statusCode() != 204) {
        throw new RuntimeException("Delete file failed: " + response.statusCode());
    }
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml DELETE /api/data/files/{id}/
openapi: 3.0.3
info:
  title: Soar Labs API - Insider Dev preview
  version: 0.1.0
  description: <b>Soar Labs Advanced RAG platform</b>
servers: []
security: []
paths:
  /api/data/files/{id}/:
    delete:
      tags:
        - Resources
      description: >-
        File creation API using Django Rest Framework.


        This viewset provides CRUD operations for File objects associated with a
        Corpora.
      operationId: api_data_files_destroy
      parameters:
        - in: path
          name: id
          schema:
            type: string
            format: uuid
          description: A UUID string identifying this File.
          required: true
      responses:
        '204':
          description: No response body
      security:
        - jwtHeaderAuth: []
        - jwtCookieAuth: []
        - cookieAuth: []
        - basicAuth: []
components:
  securitySchemes:
    jwtHeaderAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    jwtCookieAuth:
      type: apiKey
      in: cookie
      name: soar-app-auth
    cookieAuth:
      type: apiKey
      in: cookie
      name: sessionid
    basicAuth:
      type: http
      scheme: basic

````