Search, download, and maintain files
Bergur DavidsenUpdated 2026-07-14
Workspace files remain useful only when people and tools can identify the right asset and understand its state. Search within the correct workspace, inspect metadata before downloading, and review attachments before changing or deleting a file.
Search from the dashboard
- Open the workspace and select Files.
- Search by filename or descriptive terms.
- Apply tag or file-type filters where exposed.
- Open the likely file's details.
- Confirm its workspace, name, type, tags, status, and date.
- Check its fragment relationships before acting.
Use descriptive queries rather than relying on a generic filename such as final.pdf.
Search through MCP or REST
search-files provides the MCP file-metadata search path. Supply the exact workspace ID, a focused query, and a bounded limit.
The public REST file-search surface supports workspace-scoped query and metadata filters such as tags or MIME types where documented. Use GET /api/docs from the target environment for exact query encoding.
Search results are metadata, not file contents. Use get-file or the authorized REST metadata route to verify the selected object.
Inspect before downloading
Before download, check:
- filename and MIME type;
- size and processing status;
- workspace and owner context;
- tags and relevant dates;
- whether the file is still attached to maintained fragments;
- whether local handling is permitted.
A signed download URL can be temporary and sensitive. Do not store it as a durable fragment link, log it, or share it beyond its intended user and lifetime.
Download safely
Use the dashboard download action, an authorized REST route, or the download reference returned by get-file. Keep authentication and authorization checks on the server.
After download:
- scan untrusted content;
- store it only in an approved local or service location;
- preserve data classification and retention requirements;
- delete temporary local copies when no longer needed.
Do not assume previewing a file proves it is safe to execute.
Maintain metadata
Clear filenames and tags reduce duplicates. Where the UI or REST API exposes metadata updates:
- correct ambiguous names;
- keep useful topic, source, and version tags;
- remove misleading or obsolete tags;
- avoid putting secrets or personal information in metadata;
- update related fragment prose when a source is superseded.
Renaming a file does not rewrite Markdown links or external references automatically. Verify downstream use.
Remove stale files
Before deletion:
- Inspect every known fragment attachment.
- Search for related references and replacement files.
- Confirm retention and audit requirements.
- Detach or update relationships intentionally.
- Require confirmation for bulk deletion.
- Verify that the file is no longer returned or downloadable.
Bulk delete is appropriate for a reviewed, deterministic set—not a model-selected search result without human inspection.
Distinguish failure states
- Missing: the ID is wrong, deleted, or inaccessible.
- Processing: upload was accepted but is not ready.
- 403: authentication succeeded but access is insufficient.
- Failed/canceled: processing did not complete; inspect before retry.
- Deleted: the underlying asset is gone even if stale attachment metadata or prose remains.
A 404 can intentionally hide an object from an unauthorized caller. Do not reveal existence across workspace boundaries.
Troubleshooting
Search cannot find a new file
Verify the workspace, clear filters, search by exact filename, and allow asynchronous processing/indexing to finish.
Download returns 403
The current identity lacks access to the file's workspace or download action. Recheck membership and token scope.
The filename changed but links broke
Update static Markdown or external references. Prefer attachment relationships over durable use of temporary download URLs.
A file cannot be deleted
Check permission, processing state, attachments, and retention rules. Do not bypass safeguards with a bulk operation.