Uploading Documents

A base can receive content through four paths:

• Text Block, to write or paste one item;
• File, to extract text from a document;
• Website, to discover and synchronize pages from a URL (available on paid plans);
• Import CSV, to create multiple text items in bulk or make the base match a spreadsheet.

The first three are under Knowledge Bases → open the base → Add Item. Bulk import uses Import CSV at the top of the base itself. The bases.write capability is required; bases.view allows someone to inspect the base but not add or edit items.

Add a text block

The initial tab on the Add Item screen is Text Block.

1. Under Item Name, enter a name that identifies the subject, up to 100 characters.
2. Under Content, write or paste up to 100,000 characters. The editor supports Markdown.
3. Select Add Item.

The item is created as Pending and proceeds to extraction, chunking, and indexing. Its name does more than organize the list: it accompanies the chunks in the index and can help retrieval. Prefer Return policy — United States over Document 1.

Upload a file

On the File tab, SquadOS accepts one file per upload, up to 10 MB.

Content	Accepted extensions
PDF	.pdf
Word	.docx
Excel	.xlsx
HTML	.html, .htm
JSON	.json
CSV or TSV	.csv, .tsv
Markdown	.md, .markdown
Plain text	.txt

1. Fill in Item Name, or choose the file first to use its name automatically without the extension.
2. Drag the document onto the upload area or use the file picker.
3. Check that no size, format, or content-mismatch message appeared.
4. Select Send File.

The file is kept in private storage. The processor downloads the source, extracts its structure, splits the content, and creates the searchable index. Legacy Office files, presentations, ebooks, email messages, and images cannot be ingested directly: the UI tells you to convert the material to an accepted format or paste its text.

After extraction, use View to read the recovered content. Edit is available only for items created as a Text Block; to change a File item’s source, remove it and upload the correct document. The name and extracted text remain available in the view dialog.

Caution

The file-signature check runs just after selection. If the UI says that the content does not match the extension, do not submit it: remove the selection and choose the correct file. The current product does not show a visual state while this short read finishes.

Index a website

Use the Website tab to turn public pages from a domain into base items. Site sync is available on paid plans: in an organization on the Free plan, the tab shows the Site sync invitation with a See plans button instead of the form.

1. Enter the Initial URL.
2. Choose a Sync frequency: Manual, Daily, Weekly, or Monthly.
3. If needed, open Advanced to set a name, limit the crawl by path prefix, exclude paths, and change the maximum page count. The initial value is 500.
4. Select Preview pages.
5. Review the number found, the pages remaining after exclusions, the credit cost, and the organization balance.
6. Select Confirm and start crawl.

Confirmation is unavailable when no effective pages were found or the balance cannot cover the cost. A frequency other than Manual creates future synchronizations, which can also consume credits. The website must be reachable by the crawler; pages that require JavaScript or a domain without a sitemap may not appear in the preview.

Each website syncs once a day

The same website syncs at most once every 24 hours, both on schedule and through Sync now. While the window is closed, the website card shows Syncs again followed by the remaining time, and Sync now is unavailable.

The limit does not change the frequency you chose: Weekly and Monthly keep working as they are, and Daily already respects the 24-hour interval. An attempt that never starts the crawl — when the crawler rejects the address, for example — does not consume the day’s window.

Websites in an organization on the Free plan

Websites created earlier stay listed and the content already indexed remains in the base, available to agents. They stop syncing: the card shows Sync paused: available on paid plans and Sync now is unavailable until the organization moves to a paid plan.

Import multiple items from CSV

Import CSV, at the top of the base, opens Import items from CSV. The button appears for people with bases.write. First choose, under What to do with the file:

• Add items (bases.write): adds the items in the file. What is already in the base stays as it is.
• Sync base (bases.write and bases.delete): makes the base match the file. Any item not in it goes to the trash and stays there for seven days. The option appears only for people with both capabilities.

Then upload the file. SquadOS reads and analyzes the file on the server and shows what will change before touching any item: the analysis writes nothing to the base, and nothing changes until you confirm.

File format

• a semicolon (;) as the separator;
• UTF-8 text;
• title;content or id;title;content as the first row, in that order;
• one row per item, with the same number of columns as the header;
• double quotes when a field contains a semicolon, a quote, or a line break;
• two double quotes ("") to represent a quote inside an already quoted field.

The title is required and accepts up to 100 characters; spaces at either end are removed. The content is required, accepts up to 100,000 characters, and is saved exactly as it appears in the file, including spaces and line breaks. Blank rows are ignored. The file can be up to 50 MB, with no row limit; a larger file is refused on upload.

Minimal example:

title;content
"Return window";"A return can be requested within 30 days."
"Support hours";"Monday through Friday, 8:00 AM to 6:00 PM."

Add items

Each row becomes a new text item. Use the title;content header; the id column is accepted only when empty. A filled id in any row blocks the whole file, because updating items that already exist is the job of Sync base. In this mode, the dialog offers Download example spreadsheet. Its sample rows are written in Portuguese; replace them with your own data.

Sync base

Start from this base’s export: it already carries each item’s id. Download the file from Export CSV, edit it, and upload it with the id;title;content header. When syncing:

• a row with an id updates that item’s title or content. The id must belong to an item in this base and appear only once in the file;
• a row without an id becomes a new item;
• a text item in the Trash comes back to the base when its id is in the file, already carrying the row’s changes;
• a text item missing from the file goes to the trash and stays there for seven days; to recover it, use Restore on the base’s Trash tab. An item that was already in the Trash stays there, with its original deadline;
• items that came from File or Website are not edited through the CSV. Their row must keep the title and content from the export, and if they are missing from the file, they are preserved instead of going to the trash. To change one of these items, replace its source: upload the correct document or sync the website.

A difference only in the kind of line break, such as the one Excel writes when saving, does not count as a content change. When the content of an optimized item changes through the CSV, the file’s text replaces the optimized version.

The export puts an apostrophe in front of values that begin with =, +, -, @, a tab, or a carriage return, so the spreadsheet does not run them as formulas. Syncing removes that apostrophe only from rows with an id, and the content comes back exactly as it was. In a row without an id, and in Add items, a leading apostrophe is kept as part of the text.

Fix problems in the file

Any problem blocks the whole import: nothing is applied, not even the valid rows. The dialog states how many problems are blocking the import and shows a table with Line, Field, Value, Problem, and How to fix. The line is the line in the file: the header is line 1, and blank lines also count.

The analysis keeps going to the end of the file, so the report lists every problem at once. The screen shows the first 50; beyond that, use Download the full report. The most common causes are a header other than the expected one, a row with the wrong number of columns, an empty or overly long title or content, a repeated id, an id that does not belong to this base, and an item that is still being processed. Fix the spreadsheet, select Back, and upload the file again.

Review the preview and apply

When the file passes the analysis, the preview always shows the plan’s seven categories, even those at zero: Added, Unchanged, Title updated, Content updated, Restored, To the trash, and Files and crawls preserved. If any item is going to the trash, the dialog lists the names. When a category goes over 50 items, Download the full preview provides the complete list. If the file describes the base exactly as it already is, the preview says that nothing will change.

To apply, select Add items or Sync base. When syncing, the first click asks for confirmation and the second one applies. The plan is applied all at once: either all of it takes effect or nothing changes. If the base changed after the preview, SquadOS does not apply the file and returns to the upload step; export the base again, redo your edits, and upload the file once more.

The receipt shows Added, Updated, Restored, In the trash, Unchanged, and Preserved. New and restored items, and items whose title or content changed, go through processing and join search as soon as it finishes; the receipt tells you how many are still being processed.

Understand processing states

State	Meaning	What to do
Pending	The item is waiting for a processor.	Wait; editing also returns the item to this state.
Processing	The source is being extracted or its chunks are being indexed.	Do not upload the same content again.
Processed	Ingestion and index storage finished.	Test real questions with the agent.
Error	Extraction or indexing failed.	Check the source; edit a text item or remove and recreate a file.

Processed does not guarantee that every question will find the answer. It confirms ingestion, not retrieval quality. For a useful validation:

1. connect the base under Agents → open the agent → Knowledge → Knowledge bases;
2. save the agent;
3. ask questions using the language customers actually use;
4. confirm that the retrieved passage supports the answer;
5. improve names, headings, and content when the information is indexed but hard to find.

See Connecting to Agents for the complete flow.

After creating a text block or uploading a file, SquadOS may also evaluate its structure and open the optimizer. Yes, optimize applies the transformation; No, use as is keeps the received content. When the plan allows optimization, closing the dialog also accepts optimization, as stated in the dialog itself. See Organizing Base Items for evaluation, reports, and reverting.

Prepare content the agent can use

• Give each item a specific name that matches customer vocabulary.
• Use headings to separate subjects; they accompany the indexed chunks.
• Keep each policy together with its conditions, exceptions, and effective date.
• Split long documents when they cover unrelated subjects.
• Remove revoked versions and duplicates to avoid contradictory answers.
• After an important import, validate the question-and-answer journey — not only the table status.