Skip to main content
Files let you give the agent knowledge that doesn’t live in your warehouse. Upload a CSV of extra data, a catalog you maintain in a spreadsheet, a PDF of business definitions, or an image of a dashboard you want to replicate — and the agent can use it when it answers. Files work in both directions. You can bring files in, and you can ask the agent to produce them: a CSV of results, a PDF summary, and other formats it can generate in the chat.

​
Two Ways to Bring a File In

Where you put a file decides how long it lasts and who else benefits from it. The rest of this page is about Context Layer files. For attaching a file to a single conversation — and for asking the agent to generate one — see Files in a Chat.

​
The Files Page

Files live under Context Layer → Files in the sidebar. The table lists each file with its File name, Size, Description, Uploaded by, Last Modified, and Status. You can search by name or description, and filter by uploader or status. The uploader filter starts set to you, so you see your own files first — clear it to see everything in the workspace. A capacity bar shows how much of your workspace’s file storage is used, broken down by approved, private, and excluded files.

​
Uploading Files

Click Upload file, or drag files onto the table. Supported formats:
  • Documents — PDF, Word (DOCX), OpenDocument (ODT), RTF, EPUB, PowerPoint (PPTX)
  • Text — Markdown, TXT, HTML
  • Data — CSV, TSV, JSON, Excel (XLSX)
  • Images — JPEG, PNG, GIF, WEBP
Limits:
  • 50 MB per file
  • 10 files per upload
  • 5 GB total per workspace by default — your workspace may be configured with a different capacity
Uploads run one at a time, and a progress toaster tracks them. You can keep working while they finish, and cancel any that haven’t started.

​
Descriptions Make Files Discoverable

A file’s description is how the agent decides whether the file is relevant to a question. This matters more than anything else on this page. For text-based files, ClarityQ reads the file and generates a description automatically. While that’s happening the row shows as processing. For files it can’t read as text — images, mostly — a wizard opens after your upload finishes and asks you to describe each one. You can step through them, or skip: a file with no description simply won’t be found automatically, though you can still bring it into a chat by @mentioning it by name. You can edit any description later from the Description column.

​
File Statuses

Every file has one of three statuses. New uploads always start as Private. Downloading is narrower than seeing the row. Anyone who can see an Approved file can download it. A Private file’s contents stay with the person who uploaded it — admins included.
A private file’s contents are restricted to its uploader, but its row is visible to everyone in the workspace — name, description, size, and who uploaded it. Treat “private” as controlling who can open the file, not who can see that it exists. Don’t upload a file whose name or description is itself sensitive.
There are two exceptions where someone else can download a private file — both cases where you already handed it over deliberately: when you @mentioned it in a chat you shared, and when you @mentioned it in a request you sent to an analyst for review.

​
Managing Files

Each row has a menu: Download, Approve, Make private, Exclude, Re-include, and Delete. You can also select several files and act on them together. Who can do what: Approving a file makes it available to anyone in the org with access to the workspace. Making it private again removes that access. Deleting is permanent.
Files are live — they take effect as soon as you change them. Unlike metrics or entities, they aren’t part of the draft-and-deploy cycle and have no version history. See Context Layer Versioning.

​
Using Files in a Chat

Type @ in the chat and pick from the Files group to point the agent at a specific file. This works even for files with no description, and it’s the reliable way to say “use this one.” In a sent message, clicking a file mention downloads the file. Private files are marked so you can tell them apart at a glance. Behind the scenes the agent reads each file’s name, description, and type first, and downloads the contents only when it actually needs them. Excluded files are never fetched.
Files must be enabled for your workspace. If you don’t see Files in the sidebar, contact your ClarityQ representative. Files aren’t available in workspaces that answer across several other workspaces.