> ## Documentation Index
> Fetch the complete documentation index at: https://docs.file.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get all directories (folders)
> Retrieve all directories (folders) in the workspace with hierarchical structure.
This endpoint returns a paginated list of directories including their nested subfolders. Each directory includes breadcrumb navigation for easy hierarchy tracking.
Pagination is over TOP-LEVEL directories: one page row is one root folder, returned with its complete subtree. A subfolder is therefore never a page row of its own — reach it through its root's `subfolders`, or use cursor mode for a flat walk of every directory. Because a page carries whole subtrees, page size in bytes is driven by how deep those trees are; prefer cursor mode for large workspaces.
Query Parameters:
- page (optional): Page number for pagination (default: 1)
- limit (optional): Number of TOP-LEVEL directories per page (default: 100). Subfolders nested under a returned root do not count against it, so this bounds rows, NOT total directories returned — a page whose subtrees expand past 5000 directories is rejected with 400; lower `limit` or use cursor mode.
- search (optional): Case-insensitive substring match on the directory name. When present, `directories` is a FLAT list of matches — no `subfolders` nesting — and each match carries its full `breadcrumbs` path. Omit it to get the nested tree.
Response:
The response includes:
- directories: Array of directory objects with nested subfolders
- count: Total number of TOP-LEVEL directories, i.e. the number of page rows across all pages. Divide by `limit` for the page count.
- currentPage: Current page number
Each directory object contains:
- Basic information: id, name, description, status
- Hierarchy information: parentId, depth, breadcrumbs, subfolders
- Metadata: userId, organizationId, workspaceId
- Timestamps: createdAt, updatedAt
- isFromAutomatedRule: Indicates if directory was created by automation
Notes:
- Directories are returned with their complete subfolder hierarchy
- Breadcrumbs provide the full path from root to current directory
- Subfolders array contains nested directories recursively
Cursor pagination: pass the `cursor` query parameter (empty for the first page) and the response becomes `{ data, pagination: { limit, nextCursor, hasMore } }` where `data` is a FLAT list of directories — no `subfolders` nesting; each row carries its `breadcrumbs` ancestor path instead. Follow `nextCursor` until `hasMore` is false. Cursors are bound to the `search` value they were minted with; keep it identical for every page of a walk.
Retrieve all directories (folders) in the workspace with hierarchical structure. This endpoint returns a paginated list of directories including their nested subfolders with breadcrumb navigation for easy hierarchy tracking.
## Use Cases
Browse and manage your workspace folder structure programmatically
Understand folder hierarchy for automated file routing and organization
Build custom navigation interfaces with breadcrumb support
Identify folders created by automation rules for workflow tracking
## Query Parameters
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ----------- | --------------------------------------------------------------------------------- |
| search | string | No | — | Case-insensitive substring match on the directory name |
| page | number | No | 1 | Page number for pagination |
| limit | number | No | 100 | Number of **top-level** directories per page |
| sortBy | string | No | `createdAt` | Field to sort by |
| sortOrder | string | No | `ASC` | Sort direction (`ASC` or `DESC`) |
| cursor | string | No | — | Opaque cursor. Send it (empty for the first page) to switch to cursor pagination. |
This endpoint supports both pagination modes. Send the `cursor` parameter
(empty value for the first page) to use cursor pagination; omit it entirely to
keep the legacy `page`/`limit` response shape. See
[Pagination](/docs-api/api-pagination) for the full comparison.
## How pagination works here
Pagination is over **top-level** directories: one page row is one root folder,
returned with its complete subtree. A subfolder is never a page row of its own —
reach it through its root's `subfolders`, or use cursor mode for a flat walk of
every directory.
`limit` bounds page **rows**, not the total number of directories returned:
subfolders nested under a returned root do not count against it. Because a page
carries whole subtrees, its size in bytes is driven by how deep those trees are.
A page whose subtrees expand past 5,000 directories is rejected with a `400` —
lower `limit`, or use cursor mode.
In cursor mode the response is `{ data, pagination }` and `data` is a flat
list of directories with **no** `subfolders` nesting. Each row carries its
`breadcrumbs` ancestor path instead. Follow `nextCursor` until `hasMore` is
`false`. Cursors are bound to the `search` value they were minted with — keep
it identical for every page of a walk. Prefer this mode for large workspaces.
When `search` is present, `directories` is a flat list of matches with no
`subfolders` nesting, and each match carries its full `breadcrumbs` path.
Omit `search` to get the nested tree.
In offset mode, `count` is the total number of **top-level** directories —
that is, the number of page rows across all pages. Divide by `limit` for the
page count, not by the total number of directories in the workspace.
## Response Structure
### Directory Object
Each directory object contains:
| Field | Type | Description |
| ------------------- | ------- | ----------------------------------------------- |
| id | string | Unique directory identifier |
| name | string | Directory name |
| description | string | Directory description |
| status | string | Directory status (e.g., "active") |
| parentId | string | Parent directory ID (null for root directories) |
| depth | number | Depth level in hierarchy (0 for root) |
| metadata | object | User, organization, and workspace IDs |
| isFromAutomatedRule | boolean | Whether directory was created by automation |
| breadcrumbs | array | Full path from root to current directory |
| subfolders | array | Nested subdirectories (recursive structure) |
| createdAt | string | ISO 8601 timestamp of creation |
| updatedAt | string | ISO 8601 timestamp of last update |
## Understanding the Hierarchy
The `depth` field indicates how deep a folder is in the hierarchy:
* `depth: 0` - Root level folders
* `depth: 1` - First level subfolders
* `depth: 2` - Second level subfolders, and so on
The `breadcrumbs` array provides the complete path from root to the current directory:
```json theme={null}
"breadcrumbs": [
{ "id": "root-id", "name": "Parent Folder" },
{ "id": "child-id", "name": "Child Folder" },
{ "id": "current-id", "name": "Current Folder" }
]
```
The `subfolders` array contains nested directories recursively. Each subfolder has the same structure as the parent directory, allowing you to traverse the entire hierarchy.
Folders created by automation rules are marked with `isFromAutomatedRule: true`. This helps distinguish manually created folders from those generated by workflow automation.
## OpenAPI
````yaml get /prod/v1/directories
openapi: 3.0.0
info:
title: Public API
description: >-
### Welcome to fileAI’s Public API Documentation.
This API allows users to check the health of the system, upload and manage
files, and manage AI Schemas.
Should you have any questions, please reach out to fileAI via the “Contact a
Developer” link below.
[Contact a Developer](mailto:support@file.ai)
### Prerequisites
Before using our API, please ensure you complete the following prerequisites
- You must have a fileAI account. Sign up or login
[here](https://orion.file.ai/en/sign-up)
- You must have an API Key. After creating your fileAI account, you can
generate your API Key. Refer to the Authentication section below for more
details.
### Authentication
All API requests require an API key for authentication.
- To obtain your API key, please log in to your fileAI account and navigate
to Project Settings in your dashboard
- Keep your API key secure and do not share it publicly.
### How to Use Your API Key
Once you have your API key:
- Click the Authorize button on the top-right of this page
- Enter your API Key under Value
- Click Authorize to start making authenticated requests directly from the
documentation
version: '1.0'
contact: {}
servers:
- url: https://api.orion.file.ai
description: Default. Use this unless your workspace is on an instance.
- url: https://api.orion.{instance}.file.ai
description: Instance-specific host.
variables:
instance:
default: au
enum:
- au
- sg
- jp
description: >-
Instance hosting your workspace: au (Australia), sg (Singapore), jp
(Japan).
security: []
tags:
- name: Public API V1
paths:
/prod/v1/directories:
get:
tags:
- Public API V1
summary: Get all directories (folders)
description: >-
Retrieve all directories (folders) in the workspace with hierarchical
structure.
This endpoint returns a paginated list of directories including their
nested subfolders. Each directory includes breadcrumb navigation for
easy hierarchy tracking.
Pagination is over TOP-LEVEL directories: one page row is one root
folder, returned with its complete subtree. A subfolder is therefore
never a page row of its own — reach it through its root's `subfolders`,
or use cursor mode for a flat walk of every directory. Because a page
carries whole subtrees, page size in bytes is driven by how deep those
trees are; prefer cursor mode for large workspaces.
Query Parameters:
- page (optional): Page number for pagination (default: 1)
- limit (optional): Number of TOP-LEVEL directories per page (default:
100). Subfolders nested under a returned root do not count against it,
so this bounds rows, NOT total directories returned — a page whose
subtrees expand past 5000 directories is rejected with 400; lower
`limit` or use cursor mode.
- search (optional): Case-insensitive substring match on the directory
name. When present, `directories` is a FLAT list of matches — no
`subfolders` nesting — and each match carries its full `breadcrumbs`
path. Omit it to get the nested tree.
Response:
The response includes:
- directories: Array of directory objects with nested subfolders
- count: Total number of TOP-LEVEL directories, i.e. the number of page
rows across all pages. Divide by `limit` for the page count.
- currentPage: Current page number
Each directory object contains:
- Basic information: id, name, description, status
- Hierarchy information: parentId, depth, breadcrumbs, subfolders
- Metadata: userId, organizationId, workspaceId
- Timestamps: createdAt, updatedAt
- isFromAutomatedRule: Indicates if directory was created by automation
Notes:
- Directories are returned with their complete subfolder hierarchy
- Breadcrumbs provide the full path from root to current directory
- Subfolders array contains nested directories recursively
Cursor pagination: pass the `cursor` query parameter (empty for the
first page) and the response becomes `{ data, pagination: { limit,
nextCursor, hasMore } }` where `data` is a FLAT list of directories — no
`subfolders` nesting; each row carries its `breadcrumbs` ancestor path
instead. Follow `nextCursor` until `hasMore` is false. Cursors are bound
to the `search` value they were minted with; keep it identical for every
page of a walk.
operationId: PublicAPIController_getAllDirectories
parameters:
- name: search
required: false
in: query
description: >-
Case-insensitive substring match on the directory name. When
present, directories is a FLAT list of matches (subfolders empty);
each match carries its full breadcrumbs path. In cursor mode the
cursor is bound to the search value.
schema:
example: invoices
type: string
- name: page
required: false
in: query
description: Page number
schema:
default: 1
example: 1
type: number
- name: limit
required: false
in: query
description: Number of items per page
schema:
default: 100
example: 100
type: number
- name: sortBy
required: false
in: query
description: Field to sort by
schema:
default: createdAt
example: createdAt
type: string
- name: sortOrder
required: false
in: query
description: Sort direction
schema:
default: ASC
example: ASC
type: string
enum:
- ASC
- DESC
- name: cursor
required: false
in: query
description: >-
Opaque pagination cursor. Provide the parameter (empty value for the
first page) to switch to cursor pagination: the response becomes {
data, pagination: { limit, nextCursor, hasMore } } with default
limit 50 (max 100). Omit it entirely for legacy page/limit
pagination. In cursor mode sortBy must be one of createdAt,
updatedAt, _id, and cursors are bound to the sortBy/sortOrder they
were minted with.
schema:
type: string
responses:
'200':
description: >-
The directories are retrieved. Offset mode (default) returns
`{directories, count, currentPage}` as a nested tree; cursor mode
(when the `cursor` query parameter is present) returns `{data,
pagination}` where `data` is a FLAT list (no `subfolders`).
content:
application/json:
examples:
offset:
summary: Offset pagination (default, nested tree)
value:
directories:
- id: 68e4a80a0e79a0744ac72943
name: Smart folder 4
description: Smart folder 4
status: active
createdAt: '2025-10-07T05:41:30.472Z'
updatedAt: '2025-10-07T05:41:30.472Z'
depth: 0
metadata:
userId: 68e387848a36d1dd65fa064e
organizationId: 68e387848a36d1dd65fa0653
workspaceId: 68e387848a36d1dd65fa064f
isFromAutomatedRule: false
breadcrumbs:
- id: 68e4a80a0e79a0744ac72943
name: Smart folder 4
subfolders: []
- id: 68e4a79e0e79a0744ac7293d
name: Smart folder 3
description: Smart folder 3
status: active
createdAt: '2025-10-07T05:39:42.819Z'
updatedAt: '2025-10-07T05:39:42.819Z'
depth: 0
metadata:
userId: 68e387848a36d1dd65fa064e
organizationId: 68e387848a36d1dd65fa0653
workspaceId: 68e387848a36d1dd65fa064f
isFromAutomatedRule: false
breadcrumbs:
- id: 68e4a79e0e79a0744ac7293d
name: Smart folder 3
subfolders:
- id: 68e4a8060e79a0744ac72941
name: Smart folder 4
description: Smart folder 4
status: active
createdAt: '2025-10-07T05:41:26.853Z'
updatedAt: '2025-10-07T05:41:26.853Z'
parentId: 68e4a79e0e79a0744ac7293d
depth: 1
metadata:
userId: 68e387848a36d1dd65fa064e
organizationId: 68e387848a36d1dd65fa0653
workspaceId: 68e387848a36d1dd65fa064f
isFromAutomatedRule: false
breadcrumbs:
- id: 68e4a79e0e79a0744ac7293d
name: Smart folder 3
- id: 68e4a8060e79a0744ac72941
name: Smart folder 4
subfolders: []
count: 2
currentPage: 1
cursor:
summary: Cursor pagination (`cursor` param present, FLAT list)
value:
data:
- id: 68e4a8060e79a0744ac72941
name: Smart folder 4
status: active
createdAt: '2025-10-07T05:41:26.853Z'
updatedAt: '2025-10-07T05:41:26.853Z'
depth: 1
isFromAutomatedRule: false
breadcrumbs:
- id: 68e4a79e0e79a0744ac7293d
name: Smart folder 3
- id: 68e4a8060e79a0744ac72941
name: Smart folder 4
pagination:
limit: 50
nextCursor: eyJ2IjoxLCJrIjpb...
hasMore: true
schema:
oneOf:
- $ref: '#/components/schemas/GetAllDirectoriesOffsetOutput'
- $ref: '#/components/schemas/GetAllDirectoriesCursorOutput'
'401':
description: Missing or invalid API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'403':
description: Read-only or inactive API key.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'404':
description: Resource not found.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'422':
description: Validation failed.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'429':
description: Rate limit exceeded.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
'500':
description: Unexpected internal error.
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
security:
- x-api-key: []
components:
schemas:
GetAllDirectoriesOffsetOutput:
type: object
properties:
directories:
description: >-
Directory tree: one row per TOP-LEVEL directory, carrying its nested
`subfolders` recursively, and each row includes `breadcrumbs`.
Pagination applies to these root rows, so a subfolder never appears
as a row of its own. With the `search` query param the list is FLAT
matches instead (empty `subfolders`).
type: array
items:
$ref: '#/components/schemas/DirectoryForPAOutput'
count:
type: number
description: >-
Total number of top-level directories — the number of rows across
all pages, so `count / limit` is the page count. Not the total row
count of the workspace; use cursor mode to enumerate every
directory.
currentPage:
type: number
required:
- directories
- count
- currentPage
GetAllDirectoriesCursorOutput:
type: object
properties:
data:
description: >-
FLAT directory rows for this page — unlike legacy mode there is no
`subfolders` nesting (a keyset page cannot be assembled into a tree
without dropping rows whose parent falls on another page); each row
instead carries `breadcrumbs`, its ancestor-to-self path
type: array
items:
$ref: '#/components/schemas/DirectoryForPAOutput'
pagination:
$ref: '#/components/schemas/CursorPaginationMeta'
required:
- data
- pagination
ProblemDetailsDto:
type: object
properties:
type:
type: string
description: A URI identifying the problem type.
example: https://errors.file.ai/validation-failed
title:
type: string
description: Stable, human-readable summary of the problem type.
example: Validation failed
status:
type: number
description: HTTP status code.
example: 422
detail:
type: string
description: Human-readable explanation specific to this occurrence.
example: One or more fields are invalid.
instance:
type: string
description: URI reference for this occurrence (the request path).
example: /v1/files/upload
code:
type: string
description: Stable machine-readable error code.
example: VALIDATION_FAILED
requestId:
type: string
description: Correlation id for this request.
example: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors:
description: Field-level violations (validation only).
type: array
items:
$ref: '#/components/schemas/ProblemErrorItemDto'
retryAfter:
type: number
description: Seconds until the client may retry (present on 429 only).
example: 42
message:
type: string
description: Legacy key (deprecated — use `detail`/`title`).
example: Validation failed
error:
type: string
description: Legacy key (deprecated — use `title`).
example: Unprocessable Entity
statusCode:
type: number
description: Legacy key (deprecated — use `status`).
example: 422
required:
- type
- title
- status
- detail
- instance
- code
- requestId
- errors
- message
- error
- statusCode
DirectoryForPAOutput:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
status:
type: string
parentId:
type: string
nullable: true
description: >-
Parent directory id. NOT guaranteed to resolve: a directory whose
parent has been deleted or deactivated is returned as a top-level
row (depth 0, single-element breadcrumbs) while retaining the
original parentId, so fetching that id can 404. Use `breadcrumbs`
for hierarchy.
depth:
type: number
metadata:
$ref: '#/components/schemas/DirectoryMetadataForPAOutput'
isFromAutomatedRule:
type: boolean
breadcrumbs:
description: Ancestor-to-self path from the root
type: array
items:
$ref: '#/components/schemas/DirectoryBreadcrumbForPAOutput'
subfolders:
description: >-
Nested child directories (tree mode only; empty in flat/search and
cursor modes)
type: array
items:
$ref: '#/components/schemas/DirectoryForPAOutput'
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
required:
- id
- name
CursorPaginationMeta:
type: object
properties:
limit:
type: number
description: Page size applied (default 50, max 100)
nextCursor:
type: string
description: Opaque cursor for the next page; null when hasMore is false
nullable: true
hasMore:
type: boolean
required:
- limit
- nextCursor
- hasMore
ProblemErrorItemDto:
type: object
properties:
code:
type: string
example: REQUIRED
detail:
type: string
example: must not be empty
pointer:
type: string
description: JSON Pointer to the offending body field.
example: '#/fileName'
parameter:
type: string
description: Name of the offending query/header parameter.
example: limit
required:
- code
- detail
DirectoryMetadataForPAOutput:
type: object
properties:
userId:
type: string
organizationId:
type: string
workspaceId:
type: string
required:
- userId
- organizationId
- workspaceId
DirectoryBreadcrumbForPAOutput:
type: object
properties:
id:
type: string
name:
type: string
required:
- id
- name
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````