# Files and folders
Source: https://docs.file.ai/ingest/folders

> Group files into folders in the app or with the directories API, without duplicating them.

fileAI app

# Files and folders

Copy pageCopy page

Group files into folders in the app or with the directories API, without duplicating them.

Copy pageCopy page

Folders group related files so you can find, review and process them together. A folder holds references to files, not copies: every file lives once in your Drive, and the same file can sit in several folders at once. In the API, folders are called directories. See [Key concepts](/concepts) for how folders fit between projects and files.

## 

[​

](#how-it-works)

How it works

*   **One file, many folders.** Adding a file to a folder links it. Removing it, or deleting the folder, never deletes the file.
*   **Two levels by default.** A folder can have subfolders. By default a subfolder cannot have subfolders of its own; creating one returns `400` `Directory depth limit exceeded`.
*   **Rules can create folders.** A parent folder can have automation rules that sort files into subfolders it creates for you.

### 

[​

](#folder-types)

Folder types

Type

Created by

What you can do

Manual folders and subfolders

You

Upload, add and remove files; rename; delete.

Parent folders with rules

You

Delete. Deleting removes its auto-created subfolders too; the files stay in Drive.

Auto-created subfolders

A parent folder’s rules

Nothing directly: you cannot add, remove or delete here. If removed via the parent, they come back while the rules remain.

Export folders

fileAI, when you connect an integration such as Xero

Delete.

In API responses, `isFromAutomatedRule: true` marks a folder created by a rule.

## 

[​

](#use-folders-in-the-app)

Use folders in the app

1

Create a folder

Go to **Drive**, click **+** next to the Drive tab, enter a name and click **Create**.

2

Add files

Drag and drop files onto the folder, or open the folder and use the upload dialog.

3

Rename a folder

Open the folder, click the pencil icon, enter the new name and click **Confirm**.

## 

[​

](#use-folders-with-the-api)

Use folders with the API

The examples use `FILEAI_BASE_URL`, set to `https://api.orion.file.ai/prod/v1` or your [regional host](/authentication#regions).

### 

[​

](#list-folders)

List folders

```
curl "$FILEAI_BASE_URL/directories?search=invoices" \
  -H "x-api-key: $FILEAI_API_KEY"
```

Without `search`, the response is a tree: each page row is a top-level folder with its full `subfolders` and `breadcrumbs`. With `search`, it is a flat list of matching folders, each with its `breadcrumbs` path. `limit` (default 100) counts top-level folders only. For large workspaces, pass `cursor` (empty for the first page) to get a flat list with cursor pagination. See [Pagination](/api/pagination).

### 

[​

](#create-a-folder)

Create a folder

```
curl -X POST "$FILEAI_BASE_URL/directories" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Q3 invoices", "description": "Supplier invoices, July to September" }'
```

Response (201)

```
{
  "success": true,
  "directory": {
    "id": "68e4a79e0e79a0744ac7293d",
    "name": "Q3 invoices",
    "description": "Supplier invoices, July to September",
    "status": "active",
    "depth": 0
  }
}
```

Pass `parentId` to create a subfolder.

### 

[​

](#upload-straight-into-a-folder)

Upload straight into a folder

Send `directoryId` when you request an upload URL, or `destinationPath` (for example `clients/acme`) to place the file by path and create any missing folders. See [Uploads](/ingest/uploads#upload-options).

### 

[​

](#add-remove-and-move-existing-files)

Add, remove and move existing files

Action

Request

Body

Add files to a folder

`POST /v1/directories/{directoryId}/documents`

`fileIds` (1–100)

Remove files from a folder

`DELETE /v1/directories/{directoryId}/documents`

`fileIds` (1–100)

Move files to another folder

`POST /v1/directories/{directoryId}/documents/move`

`fileIds` (1–100), `targetDirectoryId`

```
curl -X POST "$FILEAI_BASE_URL/directories/68e4a79e0e79a0744ac7293d/documents" \
  -H "x-api-key: $FILEAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "fileIds": ["53d6a0b1…", "8f12c4e0…"] }'
```

Every id you send comes back in exactly one list, so a partial result is never silent:

*   **Add** returns `created`, `conflicted` (already in the folder) and `rejected` (unknown, deleted or in another workspace). The status is `201` even if every id is rejected.
*   **Remove** returns `removed` and `notAttached`.
*   **Move** returns `moved`, `conflicted` (already in the target; now removed from the source) and `notAttached` (was not in the source).

All three are safe to retry.

Attach shared reference files, such as price lists or rate cards, to every folder that needs them. Uploading the same file once per folder creates separate files and is charged a separate extraction each time.

### 

[​

](#delete-a-folder)

Delete a folder

```
curl -X DELETE "$FILEAI_BASE_URL/directories/68e4a79e0e79a0744ac7293d" \
  -H "x-api-key: $FILEAI_API_KEY"
```

This deletes the folder and every subfolder beneath it. Files are not deleted; they stay in Drive and in any other folder. The response lists `deletedDirectoryIds` and `failedDirectoryIds`. If `failedDirectoryIds` is not empty, the delete stopped part-way: retry the same call to finish.

Deleting a folder cannot be undone through the API. One request deletes at most 1,000 folders (the target plus its subfolders); a bigger tree returns `422` before anything is deleted.

To delete files themselves, use `DELETE /v1/files`. To list the files in a folder, call `GET /v1/files?directoryId=…`.

### 

[​

](#folders-with-workflows)

Folders with workflows

Folders that run a workflow, and their immediate subfolders, cannot be changed through these endpoints yet. Adding, removing, moving or deleting returns `422`. A file that is a workflow result in a folder also blocks remove, move and delete with `422`.

## 

[​

](#related)

Related

## Uploads

Upload files straight into a folder.

## AI Checklist

Check a folder’s files against your rules.

[Previous](/ask/agent-sessions)[

Validation

See where each extracted value came from in the file, and whether it has been validated.

Next

](/verify/citations-validations)

⌘I

## On this page

*   [How it works](#how-it-works)
    *   [Folder types](#folder-types)
*   [Use folders in the app](#use-folders-in-the-app)
*   [Use folders with the API](#use-folders-with-the-api)
    *   [List folders](#list-folders)
    *   [Create a folder](#create-a-folder)
    *   [Upload straight into a folder](#upload-straight-into-a-folder)
    *   [Add, remove and move existing files](#add-remove-and-move-existing-files)
    *   [Delete a folder](#delete-a-folder)
    *   [Folders with workflows](#folders-with-workflows)
*   [Related](#related)