Skip to main content

Managing Files

Finding files, editing their metadata, moving and deleting them, and checking how much space is left.

Listing and Searching Files​

List Files in a Folder​

curl -X POST https://api.travila.ai/api/v1/storage/gateway/list-files \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "folder_path": "/documents",
    "recursive": true,
    "page_size": 20
  }'

Use filter to narrow results:

{
  "folder_path": "/",
  "recursive": true,
  "filter": {
    "extensions": [".pdf", ".docx"],
    "tags": ["work"],
    "min_size_bytes": 1024,
    "uploaded_after": "2025-01-01T00:00:00Z",
    "name_contains": "report"
  }
}

Search Files​

Search across all files by name, tags, and metadata:

curl -X POST https://api.travila.ai/api/v1/storage/gateway/search-files \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly report",
    "max_results": 10
  }'

File Metadata​

Get Metadata​

curl -X POST https://api.travila.ai/api/v1/storage/gateway/get-file-metadata \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90"
  }'

Update Metadata​

Update custom metadata, tags, and description. Metadata keys are merged (existing keys not in the request are preserved):

curl -X POST https://api.travila.ai/api/v1/storage/gateway/update-file-metadata \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "metadata": {
      "reviewed": "true",
      "category": "internal"
    },
    "tags": ["notes", "reviewed"],
    "description": "Meeting notes from Q1 planning"
  }'
note

Setting tags replaces all existing tags. To add a tag, include all existing tags plus the new one.

File Operations​

Move / Rename a File​

curl -X POST https://api.travila.ai/api/v1/storage/gateway/move-file \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "destination_folder": "/archive",
    "new_name": "notes-2025-q1.txt"
  }'

Delete a File​

curl -X POST https://api.travila.ai/api/v1/storage/gateway/delete-file \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90"
  }'

Quota​

Check storage usage and limits:

curl -X POST https://api.travila.ai/api/v1/storage/gateway/get-storage-quota \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{}'

Response:

{
  "used_bytes": 1048576,
  "quota_bytes": 1073741824,
  "file_count": 15,
  "folder_count": 4,
  "usage_percentage": 0.098
}