Skip to main content

Build a searchable document library

Section: DOC-CP-files-data-managing#managing-files.

A customer who has uploaded weeks of notes and reports needs to find the right document, label reviewed work, and make room for new files. Build a library with a folder view, name/tag search, a document detail panel and deliberate cleanup.

Before you start: upload a few test documents for one authenticated application user. The examples use /documents and show individual operations for the library's interactions. Replace the sample file ID with an ID returned for your user, and keep that ID in each list item even when its name or folder changes.

Help the customer find a document​

Section: DOC-CP-files-data-managing#listing-and-searching-files.

Start with the customer's current folder, then offer search when they remember a name or tag instead of a location. Use a folder listing for browsing and filtering; use search across folders for a known document. Neither path searches inside file contents.

Populate the folder view​

Section: DOC-CP-files-data-managing#list-files-in-a-folder.

Load the first page of the customer's documents:

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

Reference: List files and folders in a directory · Request fields.

Use the listing's pagination contract when the folder contains more results. Keep the returned file IDs with the visible rows so selecting one opens the same document after a rename or move. The list-files reference describes the response and pagination fields.

A “Work reports” view can narrow the list to matching names, types and tags:

{
  "folderPath": "/",
  "recursive": true,
  "filter": {
    "extensions": [
      ".pdf",
      ".docx"
    ],
    "tags": [
      "work"
    ],
    "minSizeBytes": 1024,
    "nameContains": "report"
  }
}

Reference: List files and folders in a directory · Request fields.

An empty result should offer a way to clear these filters or upload a document. It does not mean the user's entire storage is empty.

Find a report when its folder is unknown​

Section: DOC-CP-files-data-managing#search-files.

Send the customer's query to search across their folders. This example finds PDF reports using a name or tag match, with additional criteria for a finance view:

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,
  "filter": {
    "extensions": [
      ".pdf"
    ],
    "tags": [
      "finance"
    ],
    "minSizeBytes": 1024,
    "maxSizeBytes": 52428800,
    "nameContains": "Q1"
  }
}'

Reference: Search files · Request fields.

Let the customer narrow a broad search by name or tag. Do not offer an effective date filter or a complete inventory from this capped lookup.

Let the customer review and label a document​

Section: DOC-CP-files-data-managing#file-metadata.

Selecting a result opens a detail panel with the file's current metadata and a download action. After reading the document, the customer can mark it reviewed and add the labels your application uses to organize work.

Open the selected document’s details​

Section: DOC-CP-files-data-managing#get-metadata.

Read the selected file by ID rather than using the displayed name as its identity:

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

Reference: Get file metadata · Request fields.

Show the returned details, then request a fresh download link when the customer opens the file. A stale or deleted result should appear unavailable without preventing the customer from opening other documents. See the metadata reference.

Save the review labels without erasing other labels​

Section: DOC-CP-files-data-managing#update-metadata.

Read the latest metadata, merge the customer's changes in your application, and submit the complete metadata map and complete nonempty tag list you intend to keep. For a document whose intended final labels are those below:

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

Reference: Update file metadata · Request fields.

Refresh the detail panel and relevant filtered list after saving. Coordinate simultaneous edits so one writer does not erase another's changes: the supplied metadata map replaces the stored map, and a nonempty tag list replaces the old list.

Keep completed work out of the active library​

Section: DOC-CP-files-data-managing#file-operations.

Offer an archive action for documents the customer wants to keep, and a separate delete action for files they no longer need. Moving a document preserves its file ID; deleting it removes the file that saved references point to.

Archive a completed document​

Section: DOC-CP-files-data-managing#move--rename-a-file.

Prepare an /archive folder if your interface needs its folder entry. Move the selected notes out of the active folder and optionally give them a more useful name:

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

Reference: Move or rename a file · Request fields.

Reload the active folder and archive view. The document should leave the first and appear in the second. Keep application references attached to the existing file ID; its logical path changes when it moves. See move-file.

Delete a document the customer no longer needs​

Section: DOC-CP-files-data-managing#delete-a-file.

Show the selected document's name and ask the customer to confirm deletion in your application. Then delete that file ID:

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

Reference: Delete a file · Request fields.

Refresh the library after success. If the response is lost, inspect whether the original file remains before presenting a final outcome. Remove its download action from your application's saved records; a saved file ID is not a retained copy. See delete-file.

Make room for another attachment​

Section: DOC-CP-files-data-managing#quota.

When a customer cannot upload another document, show their current usage and let them choose files to remove:

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

Reference: Get storage usage and quota · Request fields.

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

Reference: Get storage usage and quota · Response fields.

After deletion, check usage again and retry the intended upload when enough space is available. Quota preflight does not reserve space, so simultaneous uploads can change the remaining capacity.

The byte totals are decimal strings. Preserve their integer precision when calculating the remaining space; file and folder counts are numbers. See storage quota for the full response.

Investigate a library that looks out of sync​

Section: DOC-CP-files-data-managing#complete-state.

If a customer reports that a moved file disappeared or usage looks wrong, inspect that user's complete storage state from a controlled support or diagnostic path. Compare the saved file ID, its current path and the remaining folder entries, then refresh the affected view.

This operation returns every folder and file at once without pagination. Use paginated listings for the library interface. In a state response, folders are keyed by path and files by ID; the path inside a file record can change without changing its identity.

Document ID: DOC-CP-files-data-managing. Section identities and revisions.