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/list-files \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "folderPath": "/documents",
    "recursive": true,
    "pageSize": 20
  }'

Use filter to narrow results:

{
  "folderPath": "/",
  "recursive": true,
  "filter": {
    "extensions": [".pdf", ".docx"],
    "tags": ["work"],
    "minSizeBytes": 1024,
    "uploadedAfter": "2025-01-01T00:00:00Z",
    "nameContains": "report"
  }
}

Search Files​

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

curl -X POST https://api.travila.ai/api/v1/storage/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",
    "maxResults": 10
  }'

File Metadata​

Get Metadata​

curl -X POST https://api.travila.ai/api/v1/storage/get-file-metadata \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "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/update-file-metadata \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "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/move-file \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "fileId": "a1b2c3d4e5f60718293a4b5c6d7e8f90",
    "destinationFolder": "/archive",
    "newName": "notes-2025-q1.txt"
  }'

Delete a File​

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

Quota​

Check storage usage and limits:

curl -X POST https://api.travila.ai/api/v1/storage/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:

{
  "usedBytes": "1048576",
  "quotaBytes": "1073741824",
  "fileCount": 15,
  "folderCount": 4,
  "usagePercentage": 0.098
}

usedBytes and quotaBytes are 64-bit integers, so protojson sends them as strings; fileCount and folderCount are 32-bit and arrive as numbers. Parse accordingly rather than assuming one shape for all the counters.

Complete State​

Returns everything at once — every folder, every file, quota, and timestamps — in a single response. Intended for debugging and administrative use; it is not a listing endpoint and does not paginate, so avoid it on a hot path for a user with many files.

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

Response:

{
  "state": {
    "userId": "user_123",
    "folders": {
      "/documents": {"path": "/documents", "createdAt": "2026-03-01T10:00:00Z"}
    },
    "files": {
      "/documents/notes.txt": {
        "name": "notes.txt",
        "path": "/documents/notes.txt",
        "sizeBytes": "11"
      }
    },
    "totalSizeBytes": "1048576",
    "quotaBytes": "1073741824",
    "totalFileCount": 15,
    "totalFolderCount": 4,
    "createdAt": "2026-03-01T10:00:00Z",
    "lastModified": "2026-08-14T09:31:02Z"
  }
}

folders and files are maps keyed by path, not arrays — iterate their values rather than indexing by position.