Skip to main content
Once files are uploaded to your Space, you can manage them through the web interface, through natural language chat, or programmatically via the API.

​
Listing Files

​
Via the API

Retrieve a paginated list of files sorted by creation date (newest first): 
import requests

response = requests.get(
    "https://api.zarkai.xyz/v1/storage/files",
    headers={"x-api-key": "your_api_key"},
    params={"limit": "10"},
)

data = response.json()
for file in data["files"]:
    print(f"{file['name']} ({file['sizeBytes']} bytes) — {file['fileId']}")

if data["pagination"]["hasMore"]:
    print(f"Next page cursor: {data['pagination']['cursor']}")

​
Response

{
  "files": [
    {
      "fileId": "file-55f3fa40-9883-45d5-a877-a68264d58929",
      "name": "report.pdf",
      "sizeBytes": "1048576",
      "mimeType": "application/pdf",
      "createdAt": "2026-03-28T10:30:00Z"
    }
  ],
  "pagination": {
    "hasMore": true,
    "cursor": "eyJsYXN0S2V5IjoiZmlsZS01NWYz..."
  }
}

​
Pagination

Use the cursor parameter to paginate through results: 
curl "https://api.zarkai.xyz/v1/storage/files?limit=10&cursor=eyJsYXN0S2V5IjoiZmlsZS01NWYz..." \
  -H "x-api-key: your_api_key"

​
Via Chat

You can also list and browse files through natural language: 
{
  "messages": [{"role": "user", "content": "What files do I have?"}],
  "workspace_id": "wks-xxxxx",
  "tools": ["file_manager"]
}

​
Retrieving a File

Get a file’s contents or metadata by ID: 
import requests

response = requests.get(
    "https://api.zarkai.xyz/v1/storage/files/file-55f3fa40-9883-45d5-a877-a68264d58929",
    headers={"x-api-key": "your_api_key"},
)

data = response.json()
print(f"Type: {data['type']}")  # "content" or "metadata"
print(f"Name: {data['name']}")
print(f"Size: {data['sizeBytes']} bytes")

​
Response (files under 4 MB)

{
  "type": "content",
  "fileId": "file-55f3fa40-9883-45d5-a877-a68264d58929",
  "name": "report.pdf",
  "sizeBytes": "1048576",
  "mimeType": "application/pdf",
  "data": {
    "encoding": "base64",
    "content": "JVBERi0xLjQKJ..."
  }
}

​
Response (files 4 MB or larger)

Files 4 MB or larger return metadata only — content is not included inline: 
{
  "type": "metadata",
  "fileId": "file-55f3fa40-9883-45d5-a877-a68264d58929",
  "name": "large-video.mp4",
  "sizeBytes": "52428800",
  "mimeType": "video/mp4",
  "data": {
    "metadata": {
      "blobId": "blob-xxx",
      "quiltId": "quilt-xxx",
      "quiltPatchId": "patch-xxx"
    }
  }
}

​
Deleting a File

import requests

response = requests.delete(
    "https://api.zarkai.xyz/v1/storage/files/file-55f3fa40-9883-45d5-a877-a68264d58929",
    headers={"x-api-key": "your_api_key"},
)

data = response.json()
print(f"Deleted: {data['isDeleted']}")  # True

​
Response

{
  "fileId": "file-55f3fa40-9883-45d5-a877-a68264d58929",
  "isDeleted": true
}

​
Trash & Recovery

Deleted files are moved to Trash, where they remain recoverable for 30 days. After 30 days, files are permanently deleted and cannot be recovered. To recover a file from Trash, use the web interface — navigate to Trash, find the file, and click Restore.
Permanent deletion cannot be undone. Make sure you no longer need a file before permanently deleting it from Trash.

​
File Organization

​
Folders

Use folders to organize files by project, topic, or workflow. Folders can be created, renamed, and nested through the web interface or through File Manager chat commands.
Folder structure does not affect how AI analyzes files — it only impacts organization. You can organize files however makes sense for your workflow without impacting search or AI functionality.

​
File Operations via Chat

All file management operations are also available through natural language:
OperationExample prompt
Rename”Rename this file to Q4 Report Final”
Move”Move this file to the Projects folder”
Tag”Tag this as important”
Favorite”Add this to favorites”
Organize”Create a folder called Archive and move old files there”
See File Manager for the full list of operations.