List Objects
List objects in a bucket with prefix and pagination support.
| Endpoint | Method | Admin Required |
|---|---|---|
/api/v1/objects | GET | No |
Returns a paginated list of objects in a bucket you own. Supports prefix filtering for navigating folder structures, and an optional recursive search.
Query Parameters
bucket
string required
Name of the bucket to list objects from.
prefix
string
Filter objects by key prefix. Use for folder navigation (e.g.,
images/).delimiter
string
Character to group keys. Default:
/. Used to simulate folder hierarchy.search
string
Case-insensitive substring match against object keys under
prefix. When set, listing becomes recursive - it ignores delimiter and searches every nested folder, so the response contains only matching files, never folder entries.page
integer
Page number. Default:
1per
integer
Items per page. Default:
100Response
{
"metadata": {
"page": 1,
"per": 100,
"total": 5
},
"items": [
{
"key": "documents/",
"size": 0,
"contentType": "application/x-directory",
"etag": "",
"lastModified": "2025-01-15T10:30:00Z",
"isFolder": true
},
{
"key": "image.png",
"size": 245678,
"contentType": "image/png",
"etag": "d41d8cd98f00b204e9800998ecf8427e",
"lastModified": "2025-01-14T15:22:00Z",
"isFolder": false,
"versionId": "abc123def456",
"isLatest": true,
"isDeleteMarker": false
}
]
}
Response Fields
key
string
Object key (path). Folders end with
/.size
integer
Object size in bytes.
0 for folders.contentType
string
MIME type.
application/x-directory for folders.etag
string
MD5 hash of the object content.
lastModified
string
ISO 8601 timestamp of last modification.
isFolder
boolean
Whether this entry represents a folder (common prefix).
versionId
string
Version identifier (if versioning is enabled).
isLatest
boolean
Whether this is the latest version.
isDeleteMarker
boolean
Whether this version is a delete marker.
Errors
| Status | Reason |
|---|---|
400 | Missing bucket query parameter |
404 | Bucket not found (or not owned by you) |