> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/create-and-import.md).

# Create Workspaces and Import Files

Create file workspaces and folders in the File Library, add folders, upload files or entire folders, track progress and see why files were not uploaded in the upload panel, and delete workspaces and f

Files are stored in **file workspaces**. After creating a workspace, you can upload multiple files at once, or upload an entire folder from your computer together with its subfolders. You can also create folders within a workspace to organize your files.

## Use Case <a href="#use-case" id="use-case"></a>

A marketing specialist takes over a new product campaign whose files are scattered across email attachments, cloud drives, and colleagues' computers. She creates a “New Product Campaign” workspace in <mark style="color:blue;">My Files</mark> and drags a folder of assets prepared by a colleague straight into it; the subfolder structure is preserved as is. Then she selects <mark style="color:blue;">Upload Files</mark> from the toolbar and picks the specifications and an 11 MB product catalog PDF in one go. The upload runs in the panel at the bottom right, so she can keep organizing other folders while she waits. The panel flags a 0 KB empty file in the folder that was not uploaded, and she asks her colleague for the correct file. From then on, whenever she needs to find information or ask AI to organize it, she starts from this workspace.

***

## Create a File Workspace <a href="#create-workspace" id="create-workspace"></a>

### 1. Select a Space <a href="#select-space" id="select-space"></a>

Click <mark style="color:blue;">File Library</mark> in the left menu, then select the destination in the space tree: choose <mark style="color:blue;">My Files</mark> for personal content, <mark style="color:blue;">Organization Shared Files</mark> for organization-wide use (requires permission to edit the organization space), or the appropriate [shared space](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/shared-spaces.md) for use across departments.

### 2. Add a File Workspace <a href="#add-workspace" id="add-workspace"></a>

Click <mark style="color:blue;">Add File Workspace</mark> above the space tree, confirm the <mark style="color:blue;">Location</mark>, enter a <mark style="color:blue;">File Workspace Name</mark>, and click <mark style="color:blue;">Create</mark>. The new workspace appears immediately in the space tree and list.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-47ece4307d57991c2755a97a3cdc3b1734a00bf6%2Ffile-library-create-workspace.png?alt=media" alt="Add File Workspace dialog with My Files selected as the location and a file workspace name entered"><figcaption><p>The dialog shows where the workspace will be created</p></figcaption></figure>

{% hint style="info" %}
You can only create workspaces at the top level of a space; you cannot upload files directly there. At the space root, <mark style="color:blue;">Upload Files</mark> in the upload menu is disabled, so open or create a workspace first. <mark style="color:blue;">Upload Folder</mark> is still available, and an uploaded folder becomes a file workspace directly.
{% endhint %}

### 3. Add Folders (Optional) <a href="#add-folder" id="add-folder"></a>

Inside the workspace, click <mark style="color:blue;">Add Folder</mark> to organize your files further. Folders can be nested up to 10 levels deep, counting from the space root.

***

## Upload Files and Folders <a href="#import-files" id="import-files"></a>

Files and folders are uploaded to a workspace (or to a folder within a workspace). Uploading starts as soon as you select the files, and progress appears in the upload panel at the bottom right of the screen. While an upload is in progress, you can keep browsing and organizing the File Library.

### Ways to Start an Upload <a href="#upload-entry" id="upload-entry"></a>

* **Toolbar**: After opening a workspace or folder, click the upload icon in the toolbar and choose <mark style="color:blue;">Upload Files</mark> or <mark style="color:blue;">Upload Folder</mark>.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-5a61bfcd6765fcf7cc1673a54d5fd09871a81171%2Ffile-library-upload-menu.png?alt=media" alt="Upload menu in the File Library toolbar, listing Upload Files and Upload Folder"><figcaption><p>The toolbar upload button lets you choose Upload Files or Upload Folder</p></figcaption></figure>

* **Folder context menu**: Right-click a folder in the list, thumbnail view, or the space tree on the left. The first line of the menu shows the folder name. Choose <mark style="color:blue;">Upload Files</mark>, <mark style="color:blue;">Upload Folder</mark>, or <mark style="color:blue;">Add Folder</mark>, and the items go into that folder without you having to open it first.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0a6ccc76d2c8c3fa0a1e91add1fdfbf466eaa09c%2Ffile-library-folder-context-menu.png?alt=media" alt="Context menu opened on the “Quotes” folder; the first line is the folder name, followed by Upload Files, Upload Folder, Add Folder, Rename, and Delete"><figcaption><p>Upload and Add Folder in the context menu target that folder</p></figcaption></figure>

* **Drag and drop**: Drag files or folders from your computer straight into the file list. Before you release, the screen shows where they will be uploaded.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-d35e3ff799d063842bbae5b5878cf36b5ae687de%2Ffile-library-upload-drop.png?alt=media" alt="While a folder is dragged over the file list, the list border becomes dashed and a prompt below says releasing will upload to “Demo Upload Tutorial (fictional)”"><figcaption><p>While dragging, the screen shows the location the items will be uploaded to</p></figcaption></figure>

{% hint style="info" %}
Hover over a disabled option to see why it is disabled; for example, files cannot be uploaded directly at the space root. Folders synced from external sources are read-only: the context menu shows a lock icon, and Upload Files, Upload Folder, and Add Folder are all disabled.
{% endhint %}

### Upload Files <a href="#upload-files" id="upload-files"></a>

Selecting <mark style="color:blue;">Upload Files</mark> opens your computer's file picker, where you can select multiple files at once. Uploading starts as soon as you select them, with no further confirmation. The files are listed one by one in the upload panel, and up to 3 files are uploaded at the same time.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-3d052e32ce61ed9c67460f0bdb8663b736db1a83%2Ffile-library-upload-queue.png?alt=media" alt="Upload panel titled “Uploading 1 item”: one PDF is uploading with a progress bar, while blank-note.txt and editing-handbook.epub are marked as not uploaded with reasons"><figcaption><p>The upload panel shows progress for each file; files that were not uploaded show the reason</p></figcaption></figure>

Status of each file in the panel:

| Status                       | Description                                                                                                                                                                                                                                                                                                                                                                                             |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Waiting to upload            | Queued; starts once the files ahead of it finish                                                                                                                                                                                                                                                                                                                                                        |
| Uploading                    | Upload in progress, with a progress bar below                                                                                                                                                                                                                                                                                                                                                           |
| Paused · Waiting for network | The network is disconnected; the upload resumes automatically when the connection returns                                                                                                                                                                                                                                                                                                               |
| Paused                       | You paused it; click <mark style="color:blue;">Resume</mark> to continue                                                                                                                                                                                                                                                                                                                                |
| Uploaded                     | Upload complete; hover over it and click <mark style="color:blue;">Show File Location</mark>                                                                                                                                                                                                                                                                                                            |
| Not uploaded                 | The file was not sent or was rejected; the reason is shown below                                                                                                                                                                                                                                                                                                                                        |
| Upload failed                | Some files were not uploaded, and the top of the panel shows “N files failed to upload.” If the connection dropped during transfer and automatic retries still failed, click <mark style="color:blue;">Retry</mark> to send again. If the file itself does not meet the requirements (for example, it is empty or in an unsupported format), there is no Retry button; fix the file and upload it again |
| Canceled                     | You canceled the upload of this file                                                                                                                                                                                                                                                                                                                                                                    |

### Upload an Entire Folder <a href="#upload-folder" id="upload-folder"></a>

Choose <mark style="color:blue;">Upload Folder</mark> and select a folder on your computer, or drag the folder straight into the file list. The folder is created together with its subfolder structure and takes up one row in the upload panel, showing “uploaded / total files.” If some files were not uploaded, expand “N files not uploaded” to see each file's path and the reason.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-ec5a1f055b15a8227a43b8fcdec5922d968700b5%2Ffile-library-upload-folder-result.png?alt=media" alt="Demo project data folder in the upload panel showing 3 / 5 files; expanded, it lists 2 files not uploaded: editing-handbook.epub (unsupported format) and blank-note.txt (file is empty)"><figcaption><p>A folder takes up one row; expand it to see which files were not uploaded and why</p></figcaption></figure>

When uploading a folder:

* Hidden files and folders (such as `.git` and `.DS_Store`), as well as the system-generated `Thumbs.db` and `desktop.ini`, are skipped silently and are not listed as not uploaded.
* Files in unsupported formats, files over the size limit, and empty (0 KB) files are not sent. They are listed under the not-uploaded entries on that row, and the row is marked “Upload failed,” but the other files are still uploaded as usual. If a subfolder contains only such files, that subfolder is not created.
* If a folder with the same name already exists at the destination, the entire folder is not uploaded and the screen shows “A folder with the same name already exists.” Rename it first, then upload again.

{% hint style="info" %}
**Empty folders are created only by drag and drop.** When you select a folder with <mark style="color:blue;">Upload Folder</mark>, the browser provides only a list of files, so a folder with no files in it does not appear in the File Library. To keep an empty folder, drag the folder from your computer straight into the file list. A folder that contains only hidden files such as `.DS_Store` does not count as empty and is not created.
{% endhint %}

### Actions During an Upload <a href="#during-upload" id="during-upload"></a>

* **Pause and cancel**: Click <mark style="color:blue;">Pause</mark> on an item that is uploading, then <mark style="color:blue;">Resume</mark> later; click <mark style="color:blue;">Cancel Upload</mark> if you no longer want to upload it. For items that were not uploaded or failed, click <mark style="color:blue;">Remove</mark> to clear them from the panel.
* **Network disconnection**: The upload pauses and the panel shows “Network connection lost. Uploads will resume automatically.” When the connection returns, uploading continues from where it stopped, so you do not need to select the files again. Files that receive no response are resent automatically several times, and are marked “Upload failed” only if they still fail.
* **Closing the panel**: If items are still uploading or waiting, you are first asked “Cancel upload?”; if everything has finished, the panel simply collapses.
* **Leaving the File Library**: If items are still uploading or waiting, switching to another page or another organization first brings up “Leave File Library?”. Click <mark style="color:blue;">Continue Uploading</mark> to stay on the page and keep uploading; click <mark style="color:blue;">Leave and Cancel Upload</mark> to cancel the unfinished items and leave. When you close the tab or refresh, the browser also asks for confirmation first.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-41dcf00fcfbcecead9a92d75c9732532b61d3250%2Ffile-library-upload-leave-confirm.png?alt=media" alt="“Leave File Library?” confirmation dialog explaining that uploading and waiting items will be canceled, with buttons Continue Uploading and Leave and Cancel Upload"><figcaption><p>Leaving the File Library while files are uploading asks you to confirm first</p></figcaption></figure>

### Supported Formats and File Size <a href="#supported-formats" id="supported-formats"></a>

| Type            | Formats                                                        |
| --------------- | -------------------------------------------------------------- |
| Documents       | PDF, DOC, DOCX, PPT, PPTX, XLS, XLSX, CSV, TXT, MD, JSON, HTML |
| Images          | PNG, JPG, JPEG, GIF, WebP                                      |
| Audio and Video | MP3, WAV, M4A, MP4                                             |

The limit for Upload Files and Upload Folder is **500 MB** per file, and empty (0 KB) files cannot be uploaded. <mark style="color:blue;">Upload New Version</mark> in the file details is still limited to 10 MB per file; see [Online Editing](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/online-editing.md).

When a file is not uploaded, the upload panel shows the reason:

| Reason                                                  | What to do                                                                  |
| ------------------------------------------------------- | --------------------------------------------------------------------------- |
| File is empty (0 KB)                                    | Check the file content and upload again                                     |
| Unsupported format (.extension)                         | Convert it to a format supported in the table above                         |
| Exceeds the 500 MB per-file limit                       | Compress or split the file                                                  |
| A file with the same name already exists in this folder | Rename it first, or delete the old file in the folder                       |
| Not enough storage                                      | Delete files you no longer need, or contact your organization administrator |

***

## Delete a Workspace or Folder <a href="#delete-workspace-or-folder" id="delete-workspace-or-folder"></a>

Right-click a workspace card or folder (or click <mark style="color:blue;">⋯</mark>) and select <mark style="color:blue;">Delete</mark>.

{% hint style="warning" %}
You can only delete **empty** workspaces or folders: delete or move their files first. Deleting a workspace also removes its empty folders, workspace instructions, and version history. You cannot delete space roots or system folders such as <mark style="color:blue;">Temporary Storage</mark>.
{% endhint %}

***

## Related Pages <a href="#related" id="related"></a>

* [Search, Filters, and File Details](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/search-and-details.md)
* [Use Workspaces in MaiGPT](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/use-in-maigpt.md)
* [Version History and Restore](https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/versions.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/work/file-library/create-and-import.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
