> ## Documentation Index
> Fetch the complete documentation index at: https://docs.byteport.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# List Objects
> List the objects stored at a location.
List the objects at a location. Byteport decrypts the location's stored secret
in-memory, connects to the provider, and returns the entries at the requested
path — files and folders, with sizes and modified times where the backend
reports them.
Address the location the same way as the
[Locations](/api-reference/locations/get) endpoints: by **`name`** or **`id`**
in the request body (a non-unique `name` returns `409` with the candidates).
Scope the listing with:
* **`path`** — a subfolder relative to the location's root. Omit it to list the
root. For bucket/container backends (S3-family, GCS, Azure), an empty `path`
lists your **buckets/containers**, not their contents — set `path` to a bucket
name to go inside.
* **`recurse`** — set `true` to descend into subfolders. Defaults to `false`.
```bash cURL theme={null}
curl -X POST https://api.byteport.com/v1/list \
-H "Authorization: Bearer $BYTEPORT_API_KEY" \
-H "User-Agent: my-app/1.0" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-backups",
"path": "archives",
"recurse": false
}'
```
```javascript JavaScript theme={null}
const res = await fetch("https://api.byteport.com/v1/list", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.BYTEPORT_API_KEY}`,
"User-Agent": "my-app/1.0",
"Content-Type": "application/json",
},
body: JSON.stringify({
name: "prod-backups", // or id: "..."
path: "archives", // optional; empty lists the root
recurse: false, // optional
}),
});
const { entries, hint } = await res.json();
```
```python Python theme={null}
import os, requests
res = requests.post(
"https://api.byteport.com/v1/list",
headers={
"Authorization": f"Bearer {os.environ['BYTEPORT_API_KEY']}",
"User-Agent": "my-app/1.0",
},
json={
"name": "prod-backups", # or "id": "..."
"path": "archives", # optional; empty lists the root
"recurse": False, # optional
},
)
listing = res.json()
```
```json 200 OK theme={null}
{
"entries": [
{
"name": "2026-04-21.tar.gz",
"path": "archives/2026-04-21.tar.gz",
"size": 10485760,
"isDir": false,
"mimeType": "application/gzip",
"modTime": "2026-04-21T17:02:11Z"
},
{
"name": "daily",
"path": "archives/daily",
"size": 0,
"isDir": true
}
]
}
```
```json 200 OK (root listing on a bucket backend) theme={null}
{
"entries": [
{ "name": "prod-backups-bucket", "path": "prod-backups-bucket", "size": -1, "isDir": true }
],
"hint": "path was empty, so these entries are your top-level BUCKETS, not the files inside them. Set \"path\" to a bucket name to list its contents (e.g. \"path\":\"\"), or \"/\" to go deeper."
}
```
```json 404 Not Found theme={null}
{
"error": 404,
"message": "path not found: no such bucket or folder. Check the name (case-sensitive) and put the bucket/container in \"path\"; an empty bucket can also read as not-found."
}
```
## OpenAPI
````yaml POST /v1/list
openapi: 3.1.0
info:
title: Byteport API
description: >-
The Byteport API lets you move, share, and manage files across every storage
location connected to your workspace through a single HTTP interface.
version: 1.0.0
servers:
- url: https://api.byteport.com
security:
- bearerAuth: []
paths:
/v1/list:
post:
summary: List Objects
description: >-
List the objects at a location. Byteport decrypts the stored secret
in-memory, connects to the provider, and returns the entries at the
requested path.
Address the location by `name` or `id` (the same targeting as the
Locations endpoints); a non-unique `name` returns `409` with the
candidates. Scope the listing with `path` (a subfolder relative to the
location's root — empty lists the root) and `recurse` (descend into
subfolders). For bucket/container backends (S3-family, GCS, Azure) an
empty `path` lists the **buckets/containers** themselves — set `path` to
a bucket name to see its contents. When the response is empty or
potentially surprising, a non-fatal `hint` explains why.
requestBody:
required: true
content:
application/json:
schema:
type: object
description: >-
Address the location by `name` or `id` (at least one required),
plus an optional listing scope.
properties:
name:
type: string
description: >-
The location name (its `label`). If it matches several
locations, also send `id`.
example: prod-backups
id:
type: string
description: >-
The location's UUID. Addresses one location directly, or
selects a match of a non-unique `name`.
example: 3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83
path:
type: string
description: >-
Subfolder to list, relative to the location's root. Omit or
leave empty to list the root. For bucket/container backends,
set this to a bucket name to list its contents.
example: archives
recurse:
type: boolean
description: >-
List subfolders recursively. Defaults to `false` (immediate
children only).
default: false
example: false
responses:
'200':
description: The objects at the requested path.
content:
application/json:
schema:
type: object
properties:
entries:
type: array
items:
$ref: '#/components/schemas/ObjectEntry'
hint:
type: string
description: >-
A non-fatal troubleshooting note — e.g. that an empty
`path` on a bucket backend listed buckets, not their
contents, or that a path returned nothing. Omitted when
there's nothing to add.
'400':
$ref: '#/components/responses/Error'
'401':
$ref: '#/components/responses/Error'
'403':
description: >-
The provider denied access (permissions or scopes). The message
names the likely cause.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: >-
No location matched the target, or the path was not found (no such
bucket/folder).
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: The `name` matches more than one location; resend with an `id`.
content:
application/json:
schema:
$ref: '#/components/schemas/LocationConflict'
'501':
description: This credential variant cannot be listed.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'502':
description: >-
The provider listing failed for another reason; the message is
passed through.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'504':
description: The provider timed out.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
ObjectEntry:
type: object
description: One object (file or folder) at a location.
properties:
name:
type: string
description: The object's base name (last path segment).
example: 2026-04-21.tar.gz
path:
type: string
description: The object's path relative to the listing root.
example: archives/2026-04-21.tar.gz
size:
type: integer
format: int64
description: >-
Size in bytes. `-1` when the backend doesn't report a size; `0` for
directories.
example: 10485760
isDir:
type: boolean
description: >-
Whether this entry is a directory (folder/prefix) rather than a
file.
example: false
mimeType:
type: string
description: >-
The object's MIME type, when the backend reports one. Omitted
otherwise.
example: application/gzip
modTime:
type: string
format: date-time
description: >-
Last-modified time (RFC 3339), when the backend reports one. Omitted
otherwise.
example: '2026-04-21T17:02:11Z'
Error:
type: object
required:
- error
- message
properties:
error:
type: integer
message:
type: string
LocationConflict:
type: object
description: >-
Returned with `409` by a single-location endpoint when the `name` in the
body matches more than one location. Re-issue the request with an `id`
field set to one of the candidates.
properties:
error:
type: string
description: Human-readable explanation of the ambiguity.
example: >-
name is not unique; re-issue with an "id" field for one of the
candidates
name:
type: string
description: The ambiguous location name from the request body.
example: prod-backups
candidates:
type: array
description: >-
Every location that carries this name. Choose one and resend with
its `id`.
items:
$ref: '#/components/schemas/LocationRef'
LocationRef:
type: object
description: >-
A credential addressed by its label ("location name"). Because labels
are not unique, a single name can resolve to several of these.
`provider` and the timestamps let you tell same-named credentials apart
and pick the `id` to act on.
properties:
id:
type: string
description: >-
The credential's UUID. Pass it back as the `?id=` query parameter to
disambiguate a non-unique name on the mutating Locations endpoints.
example: 3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83
provider:
type: string
description: The storage backend this credential authenticates against.
example: s3
created_at:
type: string
format: date-time
description: When the credential was created (RFC 3339, UTC).
example: '2026-05-14T17:02:11Z'
updated_at:
type: string
format: date-time
description: When the credential was last modified (RFC 3339, UTC).
example: '2026-06-01T09:44:20Z'
responses:
Error:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
````