​
📁 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: 
curl -X POST "https://api.invaro.ai/api/v1/files/upload" \
  -H "Authorization: Bearer your_api_key" \
  -F "files=@document.pdf"
Response: 
{
  "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: 
curl "https://api.invaro.ai/api/v1/files?page=1&page_size=10&type=invoice" \
  -H "Authorization: Bearer your_api_key"
Response: 
{
  "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: 
curl "https://api.invaro.ai/api/v1/files/72f574a0-b3d2-4a0f-8527-f542e6ea7500" \
  -H "Authorization: Bearer your_api_key"
Response: 
{
  "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: 
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: 
curl -X DELETE "https://api.invaro.ai/api/v1/files/72f574a0-b3d2-4a0f-8527-f542e6ea7500" \
  -H "Authorization: Bearer your_api_key"
Response: 
{
  "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