List Files

Sprint 3

List user's uploaded files with storage_file_id. This endpoint is used to get storage_file_id for selecting files when creating data sources.

Endpoint

GET /api/v1/storage/files

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>

Query Parameters

Parameter	Type	Required	Description
file_category	string	No	Filter by file category: data_source, profile_image, general
page	integer	No	Page number (default: 1, min: 1)
page_size	integer	No	Items per page (default: 20, min: 1, max: 100)

Response

Success (200)

{
  "success": true,
  "data": {
    "items": [
      {
        "storage_file_id": 1,
        "file_name": "report.csv",
        "object_name": "organizations/1/files/123/report_20241203_101500_abc123.csv",
        "size_bytes": 1024000,
        "size_mb": 0.98,
        "content_type": "text/csv",
        "file_category": "data_source",
        "uploaded_at": "2024-12-03T10:15:00Z",
        "presigned_url": "https://storage.example.com/...",
        "data_source_id": null,
        "workspace_id": 1
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total_count": 15,
      "total_pages": 1,
      "has_next": false,
      "has_previous": false
    }
  },
  "message": "Files retrieved successfully"
}

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing authentication token
500	INTERNAL_SERVER_ERROR	Failed to list files

Features

• Returns storage_file_id for use in data source creation
• Pagination support
• Filter by file category
• Includes presigned URLs (valid for 1 hour)
• Shows file size in bytes and MB
• Returns linked data_source_id if file is used by a data source
• Only shows non-deleted files

File Categories

• data_source: Files used for data sources
• profile_image: User profile images
• general: General purpose files

Important Notes

• storage_file_id: This is the ID you need when creating a data source with file_path
• Files are sorted by upload date (newest first)
• Presigned URLs are valid for 1 hour
• Only files uploaded by the current user are returned

Example

curl -X GET "https://api.rivergen.com/api/v1/storage/files?file_category=data_source&page=1&page_size=20" \
  -H "Authorization: Bearer <access_token>"

Related Endpoints

• Upload File - Upload a new file
• Data Sources - Create - Use storage_file_id to create data source