> ## 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 Overview

> Comprehensive file management with enhanced features and better organization

## 📁 Files API (NEW)

The new Files API provides comprehensive file management capabilities with better organization and additional features compared to the legacy upload endpoint.

### Key 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

### Available Endpoints

| Endpoint                    | Method | Description                                         |
| --------------------------- | ------ | --------------------------------------------------- |
| `/files/upload`             | POST   | Upload files with automatic document type detection |
| `/files`                    | GET    | List files with filtering and pagination            |
| `/files/{file_id}`          | GET    | Get detailed file information                       |
| `/files/{file_id}/download` | GET    | Download original file content                      |
| `/files/{file_id}`          | DELETE | Delete files permanently                            |

### Migration from Legacy Upload

The new Files API offers several advantages over the legacy `/parse/upload` endpoint:

#### Enhanced Features

* **File Management**: Complete CRUD operations for files
* **Better Organization**: Structured file listing and filtering
* **Audit Trail**: Comprehensive tracking of file operations
* **Download Support**: Direct file download capabilities

#### Backward Compatibility

* Legacy `/parse/upload` endpoint remains functional
* Existing integrations continue to work
* Gradual migration recommended for new features

### Security Model

* **User Isolation**: Users can only access their own files
* **Bearer Token Authentication**: Consistent with existing API endpoints
* **Ownership Validation**: All operations validate user ownership
* **Audit Logging**: All file operations are logged for security

### Best Practices

1. **Use Pagination**: Always use pagination for file listings
2. **Filter Results**: Use type and status filters to reduce response size
3. **Handle Deletions**: Files are permanently removed when deleted
4. **Monitor File Sizes**: Respect the 10MB per file limit
5. **Batch Operations**: Upload multiple files in single requests when possible

### Rate Limits

The Files API follows the same rate limiting as other Invaro API endpoints:

* 100 requests per minute per API key
* Burst capacity of 200 requests
* File upload operations count as single requests regardless of file count