​
📁 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

EndpointMethodDescription
/files/uploadPOSTUpload files with automatic document type detection
/filesGETList files with filtering and pagination
/files/{file_id}GETGet detailed file information
/files/{file_id}/downloadGETDownload original file content
/files/{file_id}DELETEDelete 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