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 for how folders fit between projects and files.

​
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

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

​
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

The examples use FILEAI_BASE_URL, set to https://api.orion.file.ai/prod/v1 or your regional host.

​
List folders

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.

​
Create a folder

Response (201)
Pass parentId to create a subfolder.

​
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.

​
Add, remove and move existing files

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

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 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.

Uploads

Upload files straight into a folder.

AI Checklist

Check a folder’s files against your rules.