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

# Files API

> Comprehensive file management with better organization and additional features

## 📁 Files API (NEW)

The new Files API provides comprehensive file management capabilities with better organization and additional features.

### Upload Files

**POST** `/api/v1/files/upload`

* Upload files for processing with automatic document type detection
* Supports PDF, JPG, JPEG, PNG formats
* Maximum 50 files per request, 10MB per file
* Maintains backward compatibility with existing upload endpoint

Request:

```bash theme={null}
curl -X POST "https://api.invaro.ai/api/v1/files/upload" \
  -H "Authorization: Bearer your_api_key" \
  -F "files=@document.pdf"
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "files": [
      {
        "doc_id": "72f574a0-b3d2-4a0f-8527-f542e6ea7500",
        "type": "invoice",
        "validation": {
          "page_count": 1,
          "file_size": 84898,
          "format": "PDF"
        }
      }
    ],
    "status": "done"
  }
}
```

### List Files

**GET** `/api/v1/files`

* Retrieve paginated list of uploaded files
* Support filtering by type and status
* Exclude deleted files by default

Parameters:

* `page`: Page number (default: 1)
* `page_size`: Items per page (default: 20, max: 100)
* `type`: Filter by document type (invoice, bank\_statement, etc.)
* `status`: Filter by status (pending, processing, completed, failed, deleted)

Request:

```bash theme={null}
curl "https://api.invaro.ai/api/v1/files?page=1&page_size=10&type=invoice" \
  -H "Authorization: Bearer your_api_key"
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "files": [
      {
        "id": "72f574a0-b3d2-4a0f-8527-f542e6ea7500",
        "filename": "invoice.pdf",
        "file_id": "1234567890_invoice.pdf",
        "type": "invoice",
        "status": "pending",
        "size": 84898,
        "created_at": "2024-01-07T10:00:00Z",
        "completed_at": null
      }
    ],
    "page": 1,
    "page_size": 10,
    "total": 25
  }
}
```

### Get File Information

**GET** `/api/v1/files/{file_id}`

* Retrieve detailed information about a specific file
* Includes metadata, processing status, and validation results

Request:

```bash theme={null}
curl "https://api.invaro.ai/api/v1/files/72f574a0-b3d2-4a0f-8527-f542e6ea7500" \
  -H "Authorization: Bearer your_api_key"
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "72f574a0-b3d2-4a0f-8527-f542e6ea7500",
    "filename": "invoice.pdf",
    "file_id": "1234567890_invoice.pdf",
    "type": "invoice",
    "status": "completed",
    "size": 84898,
    "created_at": "2024-01-07T10:00:00Z",
    "completed_at": "2024-01-07T10:05:00Z",
    "processed_data": {
      // Extracted document data
    }
  }
}
```

### Download File

**GET** `/api/v1/files/{file_id}/download`

* Download the original file content
* Preserves original filename and content type
* Streams file efficiently without loading into memory

Request:

```bash theme={null}
curl "https://api.invaro.ai/api/v1/files/72f574a0-b3d2-4a0f-8527-f542e6ea7500/download" \
  -H "Authorization: Bearer your_api_key" \
  -o "downloaded_file.pdf"
```

Response Headers:

```
Content-Type: application/pdf
Content-Disposition: attachment; filename="invoice.pdf"
Content-Length: 84898
```

### Delete File

**DELETE** `/api/v1/files/{file_id}`

* Permanently delete a file from the system
* File is completely removed from the system
* Cannot be undone - use with caution

Request:

```bash theme={null}
curl -X DELETE "https://api.invaro.ai/api/v1/files/72f574a0-b3d2-4a0f-8527-f542e6ea7500" \
  -H "Authorization: Bearer your_api_key"
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "file_id": "72f574a0-b3d2-4a0f-8527-f542e6ea7500",
    "message": "File deleted successfully"
  }
}
```

### Files API Features

* **🔐 Security**: All endpoints validate user ownership - users can only access their own files
* **📄 Pagination**: Efficient pagination with configurable page sizes
* **🔍 Filtering**: Filter by document type, status, or other criteria
* **📱 Original Filenames**: Preserves and extracts original filenames from storage
* **🗑️ Delete**: Files are permanently deleted from the system
* **⬇️ Direct Download**: Stream file content with proper headers and content disposition
* **🔄 Backward Compatible**: Legacy upload endpoint remains functional