Skip to main content

Build a searchable document library

Section ID: Guide/jb50q6g14o#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 ID: Guide/jb50q6g14o#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 ID: Guide/jb50q6g14o#list-files-in-a-folder

Load the first page of the customer's documents:

Request example: List files and folders in a directory. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

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:

Request example: List files and folders in a directory. Example identifiers and values are illustrative; substitute authorized values.

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 ID: Guide/jb50q6g14o#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:

Request example: Search files. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

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 ID: Guide/jb50q6g14o#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 ID: Guide/jb50q6g14o#get-metadata

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

Request example: Get file metadata. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

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 ID: Guide/jb50q6g14o#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:

Request example: Update file metadata. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

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 ID: Guide/jb50q6g14o#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 ID: Guide/jb50q6g14o#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:

Request example: Move or rename a file. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

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 ID: Guide/jb50q6g14o#delete-a-file

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

Request example: Delete a file. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; X-On-Behalf-Of: user_123; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

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 ID: Guide/jb50q6g14o#quota

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

Response example: Get storage usage and quota. Example identifiers and values are illustrative; substitute authorized values.

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 ID: Guide/jb50q6g14o#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: Guide/jb50q6g14o