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

# Get the list of uploaded documents

> This guide explains how to retrieve and search through uploaded documents in Paradigm using the v3 API.

Retrieve a paginated list of all documents you have access to in your Paradigm instance. This endpoint supports advanced filtering, semantic search, and flexible pagination.

## Prerequisites

* A **Paradigm API key**: if you do not have one, go to your Paradigm profile and generate a new API key.
* **Access to documents**: You need appropriate permissions to view documents in your instance.

## Basic Usage

```python theme={null}
import requests
import os

api_key = os.getenv("PARADIGM_API_KEY")
base_url = os.getenv("PARADIGM_BASE_URL", "https://paradigm.lighton.ai/api/v3")

response = requests.get(
    url=f"{base_url}/files",
    headers={'Authorization': f"Bearer {api_key}"},
)

print(response.json())
```

## Response Format

```json theme={null}
{
  "next": "https://paradigm.lighton.ai/api/v3/files?page=2",
  "previous": null,
  "count": 42,
  "results": [
    {
      "id": 123,
      "filename": "report.pdf",
      "workspace_id": 5,
      "title": "Q4 Financial Report",
      "extension": "pdf",
      "status": "embedded",
      "status_vision": "embedded",
      "uploaded_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T10:35:00Z",
      "total_pages": 24
    }
  ]
}
```

## Pagination & Limits

* **Page size**: 20 documents per page (fixed)
* **`max_documents`**: Total documents to return (1-500, default: 50)
* **`page`**: Navigate through paginated results

## Available Filters

All filters are documented in the Swagger/OpenAPI specification. Key filters include:

| Filter                     | Description                                                                                                                                                                                          |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace_id`             | Comma-separated workspace IDs                                                                                                                                                                        |
| `extension`                | Comma-separated file extensions (e.g., `pdf,docx`)                                                                                                                                                   |
| `status`, `status_vision`  | Embedding status values (complete value list : <br />[https://paradigm.lighton.ai/api/v3/docs/#/Files/api\_v3\_files\_list](https://paradigm-dev.lighton.ai/api/v3/docs/#/Files/api_v3_files_list) ) |
| `title`, `filename`        | Partial match (case-insensitive)                                                                                                                                                                     |
| `uploaded_at_after/before` | Date range for upload time                                                                                                                                                                           |
| `updated_at_after/before`  | Date range for last update                                                                                                                                                                           |
| `total_pages_min/max`      | Page count range                                                                                                                                                                                     |
| `tag_id`                   | Comma-separated tag IDs                                                                                                                                                                              |

## Search

The `search` parameter enables intelligent document discovery using hybrid search. When provided, results are **ordered by relevance** instead of upload date.

```python theme={null}
response = requests.get(
    url=f"{base_url}/files",
    headers={'Authorization': f"Bearer {api_key}"},
    params={
        "search": "machine learning best practices",
        "max_documents": 20
    }
)
```

### How it Works

The DocFinder service uses a hybrid ranking approach that incorporates both semantic and lexical signals to find and rank relevant documents.

<Note>
  Filters are applied before the search, allowing you to search within a specific subset of documents.
</Note>

## cURL

```shell theme={null}
curl --request GET \
  --url "$PARADIGM_BASE_URL/files?search=financial%20report&extension=pdf" \
  --header "Authorization: Bearer $PARADIGM_API_KEY"
```