Keep your base’s files in folders

Files, in the rail under Chat, holds your base's files in folders: contracts, price lists, decks, scans. Each stays where you left it.

Files is for the base's team, the users with an admin or a staff role. A customer of the base, with an external role, as in the customer portal, has no Files.

A file attached to an item, such as an invoice on an order, stays with its item. It is not on the Files page, and moving files there never takes a file away from an item.

An admin can turn Files off for the base in Settings, General (Hide the assistant, Chat or Files); the base keeps the files, and the file fields of items continue to work.

Every user of the base's team sees every folder and every file of the Files page. A customer with an external role sees none of them. This holds on the web, through an API token, through the assistant and through an AI client alike. An agent working by itself reads them only when an admin lets it (Let agents read the Files when they work by themselves).

The Files page shows the folders at the left and the files of the folder you pick at the right. Make the folders you need, such as Contracts or Policies, and folders inside them:

1. Click New folder.
2. Give it a name and click Save.

Rename, in the folder's menu, changes its name. A folder stays where you made it: you move files, not folders.

Delete folder, in the folder's menu, deletes an empty folder only: move or delete its files and folders first, then delete it.

To upload files to the Files page:

1. Open the folder the file goes in.
2. Drag files from your computer onto the list, or click Upload and pick them. Each file may be up to 25 MB.
3. Each file shows in the list once it is uploaded, named after the file, and the page says so.

The list shows each file's name, its tags, its size, when it was last changed and by whom. The base refuses program files (Limits and details).

A file's page holds what you change on one file. Click a file to open its page. There you change its Name and its Tags, pick another Folder, see its size, its type and who uploaded it and when, click Download, or Delete it after a confirmation.

Tags are words separated by commas, such as contract, 2026. They are kept in lower case and show as badges in the list. Pick a tag in the list's tag filter to see only the files that carry it.

To move a file to another folder, drag the file's row onto a folder at the left, or use Move and pick the folder, or pick another Folder on the file's page. Only its folder changes: the file keeps its name, its tags and its date.

A JPEG or PNG picture in an item's files field shows as a small picture, in a grid, on a board's card and on the item's page. Click it to see it larger. When the picture is large, the base makes smaller copies of it for these views, so the page opens fast. The picture you uploaded stays as it is: Download and Open in new tab give it to you.

Other pictures, such as HEIC, WebP or GIF, show their icon. Click it to see the picture you uploaded.

The search box of the Files page finds a file by its name, its tags and the words inside it (full-text search). Words inside a Word file (.docx), an Excel file (.xlsx) and a PowerPoint file (.pptx) are found: type a name written in a contract and the contract shows. A PDF's words are found too once the assistant or an agent has read it (Let the assistant and agents find, read and save files); until then, a PDF is found by its name and tags. A picture is found by its name and tags only.

The same holds for the files attached to items: the search box of a list, and Search or Ctrl+K, find an order by a word inside the Word file attached to it (Find items with search and filters).

Search, or Ctrl+K, finds the files of the Files page too, the same way: by their name, their tags and the words inside them. Click one and it opens on the Files page.

Search finds only what you may see:

• a customer with an external role finds no file of the Files page;
• on a list, when a field rule hides an item's files field from your role (Hide or lock fields with field rules), the words inside its files are hidden too: the search does not find the item by them. A rule that hides the field on some items only hides those items' words, and the others are still found.

Import a zip to bring a whole set of files into Files at once, with their folders.

1. Open the folder the files go in.
2. Click Import a zip and pick a zip file.
3. The import runs while you wait, then says how many folders and files came in and how many were skipped.

What the import does:

• Each folder in the zip becomes a folder in the one you picked, or goes into a folder of the same name that is already there. Each file goes into its folder.
• Hidden files, and the extra files a Mac adds to a zip, are left out.
• A zip holds up to 1,000 files, and each may be up to 25 MB. A larger file is skipped, and the import says so.
• When the base's storage is full on the way, the import stops there and says why; what came in before stays.
• The zip itself is not kept.

Files count in the base's storage: every file of the base, those on the Files page and those attached to items. How much storage the base has, where to see it, what happens when it is full and how an owner adds more is in See, add or remove storage.

The base's Export your data, in its Settings, General (Download all of your base's data in one zip file), holds the folders of the Files page and their files, with the files attached to items. One file you download from its page, or all of them through an API token (Use Files with an API token or an AI client).

The assistant and the base's agents find and read the files you see, as you, when you ask them: in a chat or in a channel, in Base Captain or on a machine (Make AI agents that work in your base). An agent working by itself, for a schedule, an automation or a workflow step, reads them only while an admin lets it (Let agents read the Files when they work by themselves).

• Find a file: ask "Which contract mentions Northwind?" and it lists the files you see, by folder, by tag or by a word in their name, their tags or inside them, as the Files page's search does.
• Read a file: ask "What is the total on the March invoice in Contracts?" and it reads the picture or the PDF and answers.
• Save a file: ask "Keep this PDF in Contracts" about a PDF you attached in the chat, and it saves it to that folder as a new file, as if you uploaded it. A machine agent saves a file it made on the machine, and the assistant and agents in Base Captain also a page's picture (Save a file to an item or to Files). It saves only to a folder you see.

An agent working by itself cannot save to Files either: "An agent running by itself cannot reach the base's Files. Save the file to an item's files field or a new comment instead."

The words of a PDF

The first time the assistant or an agent reads a PDF of the Files page, or one in an item's files field, it also keeps the PDF's words. From then on, search finds that PDF by a word inside it, as it finds a Word file, on the Files page, on a list, with Ctrl+K and for the assistant and agents. Keeping the words of a PDF made by a program, which holds text, uses no AI. Only the first read of a scanned PDF, which holds only pictures of its pages, uses a little more of the plan's AI (What AI your plan includes), even for the assistant; a later read of the same PDF does not. A picture keeps no words, and neither does a PDF attached to a comment or sent in Chat.

Customers of a base, with an external role, get none of this. While the base keeps its data from AI (Keep your records away from AI), the assistant and every agent are refused the files, as they are refused the items.

An agent that works by itself, for a schedule, an automation or a workflow step, reads no file of the Files page at first. To let it, an admin:

1. Opens Settings, AI settings.
2. Turns on Let agents read the Files and clicks Save settings.

While Let agents read the Files is on, the base's agents with a staff role read the folders and the files of the Files page when they work by themselves: they list them, open them and read their pictures and PDFs, as their role lets them. They cannot add, change or delete a file or a folder. Turn it off the same way. While the base keeps its data from AI, agents read no files, on or off.

An agent with a builder role can still read the Files through the base's code.

Only an admin changes this setting, in the base. No assistant, agent or AI client changes it, and a change one of them asks for is refused: "Only an admin can change this, in Settings, AI settings."

Files in Base Captain have these limits:

• The base does not accept program files, such as .exe, .dll, .bat or .msi files and other programs. It knows a program by its name and also by what is inside it, so a program that someone renamed, such as a .exe renamed to .pdf, is refused too. The upload then stops with "This is a program file. The base does not accept program files, such as .exe, .dll, .bat or .msi." This holds on the Files page, in a files field of an item, in a comment's files, on a public form, through an API token and through the assistant and an AI client alike.
• A program attached to a mail that comes in is not kept, as an attachment over 25 MB is not (Get mail at your base's own address).

Files works with an API token of the base too, as you, seeing what you see (Use your base from a script with an API token). Folders and files are items of the built-in tables _folders and _files.

Routes

• GET /api/tables/_folders/items lists the folders; POST /api/tables/_folders/items makes one, with a name and a parent, and PUT and DELETE on /api/tables/_folders/items/<id> rename and delete it.
• GET /api/tables/_files/items lists files, with filter on folder or tags and q to search; GET /api/tables/_files/items/<id> reads one and GET /api/tables/_files/items/<id>/files/<uuid> downloads it.
• To upload, POST /api/files with the file's name, type and size, send the file to the address it answers, then POST /api/tables/_files/items with the file, its folder and, if you like, a name and tags.
• PUT /api/tables/_files/items/<id> changes a file's name or tags, or moves it to another folder; DELETE deletes it.
• POST /api/files/import imports a zip uploaded first, into a folder, and answers the import's background job, read with GET /api/files/background-jobs/<id>.
• GET /api/files/usage gives the bytes the base's files use.

The tools of the assistant and AI clients

• The assistant and the AI clients that reach the base through Base Captain's MCP server use the tools list_files, which finds files by folder, tag or a word q, list_folders, add_folder, update_folder, delete_folder, add_file, update_file (which also moves a file), delete_file and import_files.
• add_file files what was uploaded first with POST /api/files, or a spreadsheet attached in a chat with the assistant, in the folder you name.
• save_file, with a folder, saves a file attached in the chat, a file of a machine agent's working folder, or, for an AI client, a file it sent first with upload_file (What an AI client can and cannot do in a base).
• Their search inside items' files is the list search, list_items with a search word.
• The assistant and agents read a file with read_file, with the table _files and the file's id; an AI client through Base Captain's MCP server cannot, as a read uses the plan's AI.
• While the base keeps its data from AI, these tools are refused.