> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # File > Upload files for indexing with explicit format, size, update, and access boundaries. Use the File connector to upload approved documents, spreadsheets, PDFs, or exported files directly into AIvis knowledge. It has no source-system ACL to synchronize, so access is controlled entirely by the connector's Public or Private group configuration. ## Use cases | Scenario | Recommendation | | -------------------------- | ---------------------------------------------------------------------------------------------- | | Controlled document packet | Put files with the same audience into one connector and bind it to the matching Private group. | | Temporary project material | Remove files or delete the connector after the project ends to avoid retaining stale material. | | Spreadsheet analysis | Confirm the spreadsheet is indexed and validate code-interpreter staging when needed. | | Mixed-permission files | Split connectors by audience; do not upload files with different visibility into one batch. | ## What it indexes The File connector uploads one or more files into AIvis-managed storage and indexes each recognized file as a document. It is a load-state connector with no scheduled refresh or source system to poll. | Content | Indexing behavior | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Text and document files | Supported extensions are `.txt`, `.md`, `.mdx`, `.conf`, `.log`, `.json`, `.csv`, `.tsv`, `.xml`, `.yml`, `.yaml`, `.sql`, `.pdf`, `.docx`, `.pptx`, `.eml`, `.epub`, `.html`, `.xlsx`, and `.xlsm`. Unrecognized extensions can be stored by the upload handler but are skipped during connector processing. | | Tabular files | `.csv`, `.tsv`, `.xlsx`, and `.xlsm` become tabular sections and retain the stored file ID for code-interpreter staging. If raw-file staging is unavailable, tabular files are skipped. | | Images and embedded images | `.png`, `.jpg`, `.jpeg`, and `.webp` become image sections. DOCX and PPTX actively extract embedded images. PDF embedded images are extracted only when the deployment's image-extraction-and-analysis setting is enabled. The current EML, EPUB, HTML, XLSX, and XLSM paths do not emit embedded images. | | ZIP upload | One ZIP may be expanded by an upload request. Directories and path components beginning with `.` are skipped. A second ZIP is rejected. Files extracted from the archive still pass the extension checks above during indexing. | The normal Admin flow accepts multiple files and does not apply a file-extension filter in the browser. Uploading bytes successfully therefore does not guarantee that the connector will emit an indexed document. ## Prerequisites * Prepare files with one of the supported extensions and validate that their contents match the extension. * For encrypted PDFs, note that the normal Admin File flow creates an empty internal credential and exposes no PDF-password field. Use an unencrypted copy unless your deployment has a separate supported ingestion path. * Ensure the file-store and indexing workers can hold and process the upload. The File upload handler does not enforce a connector-specific byte limit. The current `MAX_FILE_SIZE_BYTES` indexing check only logs when a constructed document exceeds the configured value; it does not reject the upload or skip that document. * Apply deployment ingress, storage, memory, and worker limits appropriate to your environment, then test representative large PDFs, spreadsheets, images, and archives before broad use. ## Credentials | Method | AIvis behavior | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Admin File upload | No external credential is required. After storing the files and creating a load-state connector, the UI creates an empty internal credential so the connector-credential pair has an owner and can use AIvis access controls. | | PDF password | The backend connector can read a `pdf_password` value from a credential, but the normal Admin File form does not expose or populate it. Do not assume encrypted PDFs are supported by this UI flow. | Do not upload access tokens, private keys, or source-system credentials as ordinary content. A File connector indexes content; it does not use a file as an authentication credential. ## Configure in AIvis 1. In the Admin panel, open **Connectors**, select **File**, and enter a descriptive connector name. 2. Select one or more files. A ZIP is expanded by default; include at most one ZIP in the upload. 3. Review the selected file names and remove unsupported formats before creating the connector. Upload storage can accept a file that the indexing worker later skips. 4. Select AIvis **Private** groups for restricted files. Choose **Public** only when every AIvis account may search every file in the connector. 5. Create the connector. The UI uploads the files, creates the connector and internal empty credential, links them with the selected access, and starts one indexing run. 6. To revise an existing File connector, add or remove files in its management view. At least one file must remain; additions trigger update indexing and removals trigger pruning. ## Permissions File contents and descriptive owner metadata do not create source ACLs. File is not an **Auto Sync Permissions** source in the current Admin access selector. Search access is controlled only by the connector's AIvis **Private** groups or **Public** mode. Every user with connector access can search every emitted document in that File connector. Split files into separate connectors when audiences differ. File-management authorization is separate from search access. All three File management endpoints first require a curator or admin session. Upload proceeds after that role gate. Listing then checks connector access; updating then checks editable access. A global curator has a special update allowance for a Public File connector, but not for an unrelated Private connector. An ordinary connector user cannot list or update files through these Admin endpoints merely because the user can search the connector. These management rules do not create per-document search permissions. ## Verify 1. After creation, confirm the upload returns stored file names and the indexing attempt completes. 2. Search a distinctive title and sentence from each supported file type in the batch. 3. Confirm an unsupported-extension test file is absent even if upload storage accepted it. 4. For CSV, TSV, XLSX, or XLSM, inspect the extracted table and test raw-file analysis if code-interpreter staging is part of your deployment. 5. For a ZIP, compare extracted file names with the archive. Confirm hidden path entries are not indexed as documents. 6. Test every assigned AIvis group and a user outside those groups. 7. Add one file and remove one file from an existing connector, then verify the new document appears and the removed document is pruned. ## Troubleshooting | Symptom | What to check | | ---------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Upload succeeds but no document appears | Confirm the filename has a supported extension, the file record exists, and extraction produced text, a table, or an image section. Upload storage itself does not enforce the indexing extension allowlist. | | A second ZIP is rejected | This is expected. Use one archive for the connector upload, combine the archives before uploading, or use a separately supported ingestion API. | | A large upload exhausts resources | The connector upload handler has no connector-specific byte rejection, and `MAX_FILE_SIZE_BYTES` currently warns rather than blocks. Enforce deployment-level request and storage limits, reduce the batch, and test extraction memory separately. | | A tabular file is skipped | Confirm raw-file staging is configured. CSV, TSV, XLSX, and XLSM require the staging callback before tabular sections are emitted. | | Users can search files outside their source responsibility | File has no source ACL sync, and metadata owners are not authorization. Restrict the connector with AIvis Private groups or split files by audience. | ## Related pages * [Connectors & Indexing](/aivis/knowledge/connectors) * [Index Settings](/aivis/knowledge/index-settings)