List Files

Retrieve a paginated list of files from a specific bucket using the API.

This endpoint supports filtering by date, file type, access level, and pagination using cursors.

---

Prerequisites

Before you begin, make sure you have:

• A bucket created
• A JWT signed with your API Key with the scope claim set to read.

---

Request Parameters

Parameter	Type	Description
cursor	number	Offset-based pagination. Indicates the position from which to start listing
limit	number	The number of records to return per request
from	string	(Optional) Start date in ISO format (e.g., 2024-01-01)
to	string	(Optional) End date in ISO format (e.g., 2024-12-31)
access	string	(Optional) Filter by file access: public or private
file_type	string	(Optional) Filter by file type: image or video
bucket_id	string	Your bucket’s ID

---

Example Request

First, set your environment variables:

export CURSOR=0
export LIMIT=10
export FROM=2024-01-01
export TO=2024-12-31
export ACCESS=public
export FILE_TYPE=image
export BUCKET_ID=your_bucket_id
export JWT=your_jwt_token

Then make the request using curl:

curl -X GET "https://zustack.com/files/${BUCKET_ID}?cursor=${CURSOR}&limit=${LIMIT}&access=${ACCESS}&file_type=${FILE_TYPE}&from=${FROM}&to=${TO}" \
  -H "Authorization: Bearer ${JWT}" | jq

This will return a list of files along with metadata such as file_id, created_at, file_type, url, and more.

---

Response Example

{
  "data": [
    {
      "id": "121567ce-5fda-4f91-997c-c12d8abf3d46",
      "bucket_id": "f1092047-1279-42df-8109-6a930e7c8bba",
      "status": "success",
      "url": "https://video.zustack.com/public/enam/f1092047-1279-42df-8109-6a930e7c8bba/121567ce-5fda-4f91-997c-c12d8abf3d46?seek=20",
      "hls_playlist": "",
      "timeline_preview": "20",
      "thumbnail": "https://assets.zustack.com/public/enam/f1092047-1279-42df-8109-6a930e7c8bba/121567ce-5fda-4f91-997c-c12d8abf3d46/thumbnail.webp",
      "name": "video.mkv",
      "file_type": "video",
      "access": "public",
      "size": 82317535,
      "date": "Jun 24, 2025, 3:04 PM",
      "created_at": "2025-06-24T18:04:20Z"
    },
    {
      "id": "0393445a-a851-483d-bcc1-09f7371d9ea2",
      "bucket_id": "f1092047-1279-42df-8109-6a930e7c8bba",
      "status": "success",
      "url": "https://assets.zustack.com/public/enam/f1092047-1279-42df-8109-6a930e7c8bba/0393445a-a851-483d-bcc1-09f7371d9ea2.webp",
      "hls_playlist": "",
      "timeline_preview": "",
      "thumbnail": "",
      "name": "ai.png",
      "file_type": "image",
      "access": "public",
      "size": 88742,
      "date": "Jun 24, 2025, 1:52 PM",
      "created_at": "2025-06-24T16:52:10Z"
    }
  ],
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE3NTA3OTIxMzgsImlhdCI6MTc1MDc5MTgzOCwibmJmIjoxNzUwNzkxODM4LCJwcml2aWxlZ2UiOiIiLCJ1c2VyX2lkIjoiIn0.LIZ_eTNHTE0BoKIEj-sHTIjIR8_myH9ccXj4h5H5iYk",
  "nextID": 3
}

Use the nextID value to paginate through additional results in the next request.