List Objects

POST

list

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
  }'

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();

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()

{
  "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
    }
  ]
}

{
  "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\":\"<bucket>\"), or \"<bucket>/<folder>\" to go deeper."
}

{
  "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."
}

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 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.

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
  }'

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();

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()

{
  "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
    }
  ]
}

{
  "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\":\"<bucket>\"), or \"<bucket>/<folder>\" to go deeper."
}

{
  "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."
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Address the location by name or id (at least one required), plus an optional listing scope.

name

string

The location name (its label). If it matches several locations, also send id.

Example:

"prod-backups"

string

The location's UUID. Addresses one location directly, or selects a match of a non-unique name.

Example:

"3f9a2b7c-1d4e-4a8f-9c2b-6e5d0a1f7b83"

path

string

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

boolean

default:false

List subfolders recursively. Defaults to false (immediate children only).

Example:

false

Response

The objects at the requested path.

entries

object[]

Show child attributes

hint

string

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.

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
  }'

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();

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()

{
  "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
    }
  ]
}

{
  "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\":\"<bucket>\"), or \"<bucket>/<folder>\" to go deeper."
}

{
  "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."
}

Get Started

API Keys

Locations

Transfers

Authorizations

Body

Response