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

# Upload File

> Upload files to a text namespace using the Python SDK

## documents.upload\_file

Uploads a file to a text namespace. The SDK automatically requests a pre-signed upload URL, uploads the file bytes, and the backend processes and embeds the content asynchronously.

### Parameters

<ParamField query="namespace_name" type="str" required>
  The name of the target text namespace.
</ParamField>

<ParamField query="file_path" type="str | Path | BinaryIO" required>
  Path to a local file (`str` or `Path`) or a file-like object (`BinaryIO`).
</ParamField>

**Returns:** `Dict[str, Any]` - A dictionary confirming the file upload request.

Common response fields include `success`, `message`, `namespace`, `file_name`, and `file_size`.

**Raises:** `NamespaceNotFound`, `InvalidInputError`, `AuthenticationError`, `APIError`, `MoorchehError`.

### Example

```python Upload File Example theme={null}
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    status = client.documents.upload_file(
        namespace_name="my-faq-documents",
        file_path="C:/path/to/document.pdf"
    )
    print(status)
```

### Input Options

You can pass either a file path or a file-like object.

```python File Path Or File-Like Object theme={null}
from pathlib import Path
from moorcheh_sdk import MoorchehClient

with MoorchehClient() as client:
    # Option 1: Path
    result_a = client.documents.upload_file(
        namespace_name="my-faq-documents",
        file_path=Path("C:/path/to/guide.md")
    )

    # Option 2: File-like object
    with open("C:/path/to/data.csv", "rb") as f:
        result_b = client.documents.upload_file(
            namespace_name="my-faq-documents",
            file_path=f
        )

    print(result_a)
    print(result_b)
```

### Complete Example

```python Complete File Upload Workflow theme={null}
from moorcheh_sdk import MoorchehClient
import time

with MoorchehClient() as client:
    # 1. Create a namespace (once)
    client.namespaces.create("my-data", type="text")

    # 2. Upload a file
    upload_result = client.documents.upload_file(
        namespace_name="my-data",
        file_path="C:/path/to/product-faq.pdf"
    )
    print(f"Upload response: {upload_result}")

    # 3. Wait for processing before querying/searching
    print("Waiting for file processing...")
    time.sleep(5)
```

## Important Notes

<Note>
  **SDK handles pre-signed upload internally**: You do not need to call the upload URL endpoint manually when using `documents.upload_file`.
</Note>

<Note>
  **Asynchronous Processing**: Uploaded files are processed asynchronously. Allow some time after upload before searching.
</Note>

<Warning>
  **Supported file types only**: `.pdf`, `.docx`, `.xlsx`, `.json`, `.txt`, `.csv`, `.md`.
</Warning>

<Warning>
  **File size limit**: Maximum upload size is **5GB**.
</Warning>

## Best Practices

* Use clear, stable file names so ingestion and auditing are easier
* Keep source files clean and well-structured for better extraction quality
* Use markdown or plain text when possible for predictable parsing
* Upload large datasets in multiple files rather than one huge file
* Wait briefly before running search queries after upload
* Handle upload exceptions and retry transient failures

## File Limits

* **File Size**: Max 5GB
* **Supported Types**: `.pdf`, `.docx`, `.xlsx`, `.json`, `.txt`, `.csv`, `.md`
* **Upload URL Expiry**: Internally handled by SDK (short-lived pre-signed URL)

## Related Operations

* [List Files](/python-sdk/files/list-files) - List raw objects in storage for a namespace
* [Delete Files](/python-sdk/files/delete-files) - Remove file objects by name from storage
* [Fetch Text Data](/python-sdk/data/fetch-text-data) - List ingested text and summary chunks
* [Search](/python-sdk/search/query) - Query uploaded and processed content
* [Delete Data](/python-sdk/data/delete) - Remove documents or entries from a namespace