List Objects

Sprint 3

List objects in a bucket. Users can only access files under their own folder.

Endpoint

GET /api/v1/storage/buckets/{bucket_name}/objects

Headers

Header	Required	Description
Authorization	Yes	Bearer <access_token>

Path Parameters

Parameter	Type	Required	Description
bucket_name	string	Yes	Name of the bucket

Query Parameters

Parameter	Type	Required	Description
prefix	string	No	Object name prefix to filter by (must be within user's folder: organizations/{org_id}/files/{user_id}/)
recursive	boolean	No	Whether to list recursively (default: true)

Response

Success (200)

{
  "success": true,
  "data": {
    "objects": [
      {
        "name": "organizations/1/files/123/report_20241203_101500_abc123.csv",
        "size": 1024000,
        "last_modified": "2024-12-03T10:15:00Z",
        "etag": "\"d41d8cd98f00b204e9800998ecf8427e\""
      }
    ],
    "bucket": "rivergen-storage",
    "prefix": "organizations/1/files/123/",
    "user_folder": "organizations/1/files/123/"
  },
  "message": "Objects retrieved successfully"
}

Error Codes

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing authentication token
403	FORBIDDEN	Access denied - prefix must be within user's folder or bucket access denied
500	INTERNAL_SERVER_ERROR	Failed to list objects

Security

• Users can only access files under their own folder: organizations/{org_id}/files/{user_id}/
• If prefix is provided, it must start with the user's allowed path
• If prefix is not provided, defaults to user's folder
• Results are filtered to ensure all objects are within user's allowed path
• Bucket name must match the configured bucket

Features

• Recursive listing option
• Prefix filtering (restricted to user's folder)
• Automatic filtering to user's allowed path
• Returns user folder path for reference

Example

curl -X GET "https://api.rivergen.com/api/v1/storage/buckets/rivergen-storage/objects?prefix=organizations/1/files/123/&recursive=true" \
  -H "Authorization: Bearer <access_token>"

Related Endpoints

• List Files - List user's uploaded files with metadata
• Get File Metadata - Get metadata for a specific file