> ## 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.
# Create a new directory
> Create a new directory (folder) to organize your files within the workspace.
Directories can be nested by providing a parentId to create subdirectories. The system enforces a maximum directory depth limit (configurable via system settings, default is 1 level).
Request Body Parameters:
- name (required): The name of the directory
- description (optional): A description for the directory
- parentId (optional): The ID of the parent directory to create a subdirectory. If not provided, the directory will be created at the root level
Response:
The response includes the created directory object with:
- Basic information: id, name, description, status
- Hierarchy information: parentId, depth
- Metadata: userId, organizationId, workspaceId, createdBy, lastModifiedBy, etc.
- Timestamps: createdAt, updatedAt
Notes:
- The directory is created with status: "active" by default
- The authenticated user becomes the owner of the directory
- Directory depth is automatically calculated based on parent hierarchy
Create a new directory (folder) to organize your files within the workspace. Directories can be nested by providing a parentId to create subdirectories.
The system enforces a maximum directory depth limit (configurable via system
settings, default is 1 level).
## Use Cases
Create folders to organize uploaded files by category, project, or type
Build hierarchical folder structures with parent-child relationships
Programmatically create folders as part of automated workflows
Set up shared folder structures for team-based file management
## Request Parameters
### Request Body
The request body must contain a JSON object with the following properties:
| Property | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------------------------------- |
| name | string | Yes | The name of the directory |
| description | string | No | A description for the directory |
| parentId | string | No | The ID of the parent directory to create a subdirectory |
If `parentId` is not provided, the directory will be created at the root
level.
## Directory Properties
### Automatic Fields
The following fields are automatically set by the system:
| Field | Description |
| --------- | ------------------------------------------------- |
| id | Unique identifier assigned to the directory |
| status | Set to "active" by default |
| depth | Calculated based on parent hierarchy (0 for root) |
| createdAt | Timestamp when directory was created |
| updatedAt | Timestamp when directory was last modified |
| metadata | User, organization, and workspace information |
### Depth Calculation
Directories created without a `parentId` are placed at the root level with
`depth: 0`.
{' '}
When you provide a `parentId`, the system automatically calculates the depth
by incrementing the parent's depth by 1.
The system enforces a maximum depth limit (default: 1 level). Attempting to
create directories beyond this limit will result in a 400 error.
## OpenAPI
````yaml post /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
security: []
tags:
- name: Public API V1
paths:
/prod/v1/directories:
post:
tags:
- Public API V1
summary: Create a new directory
description: >-
Create a new directory (folder) to organize your files within the
workspace.
Directories can be nested by providing a parentId to create
subdirectories. The system enforces a maximum directory depth limit
(configurable via system settings, default is 1 level).
Request Body Parameters:
- name (required): The name of the directory
- description (optional): A description for the directory
- parentId (optional): The ID of the parent directory to create a
subdirectory. If not provided, the directory will be created at the root
level
Response:
The response includes the created directory object with:
- Basic information: id, name, description, status
- Hierarchy information: parentId, depth
- Metadata: userId, organizationId, workspaceId, createdBy,
lastModifiedBy, etc.
- Timestamps: createdAt, updatedAt
Notes:
- The directory is created with status: "active" by default
- The authenticated user becomes the owner of the directory
- Directory depth is automatically calculated based on parent hierarchy
operationId: PublicAPIController_createDirectory
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateDirectoryForPAInput'
responses:
'201':
description: The directory is created
content:
application/json:
example:
success: true
directory:
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
createdBy: null
lastModifiedBy: null
tags: null
version: null
isSystemManaged: null
workflowStates: null
deletedBy: null
parentId: null
id: 68e4a79e0e79a0744ac7293d
schema:
type: object
properties:
success:
type: boolean
directory:
type: object
properties:
id:
type: string
name:
type: string
description:
type: string
status:
type: string
parentId:
type: string
nullable: true
depth:
type: number
metadata:
type: object
properties:
userId:
type: string
organizationId:
type: string
workspaceId:
type: string
createdBy:
type: string
nullable: true
lastModifiedBy:
type: string
nullable: true
tags:
type: array
nullable: true
version:
type: string
nullable: true
isSystemManaged:
type: boolean
nullable: true
workflowStates:
type: object
nullable: true
deletedBy:
type: string
nullable: true
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
'400':
description: Directory depth limit exceeded
content:
application/json:
example:
message: Directory depth limit exceeded
error: Bad Request
statusCode: 400
schema:
type: object
properties:
message:
type: string
error:
type: string
statusCode:
type: number
'401':
description: Invalid API key | API key is missing
content:
application/json:
example:
message: Invalid API key | API key is missing
error: Unauthorized
statusCode: 401
schema:
type: object
properties:
message:
type: string
error:
type: string
statusCode:
type: number
'422':
description: Invalid name | Invalid parentId
content:
application/json:
example:
message: Invalid name. | Invalid parentId.
error: Unprocessable Entity
statusCode: 422
schema:
type: object
properties:
message:
type: string
error:
type: string
statusCode:
type: number
'429':
description: Too Many Requests
content:
application/json:
example:
statusCode: 429
message: Too Many Requests
schema:
type: object
properties:
statusCode:
type: number
message:
type: string
security:
- x-api-key: []
components:
schemas:
CreateDirectoryForPAInput:
type: object
properties:
name:
type: string
description: Directory name
example: Directory 1
description:
type: string
description: Directory description
example: Description
parentId:
type: string
description: Parent directory id
example: 649e2d2d2d2d2d2d2d2d2d2d
isActive:
type: boolean
description: Is active
default: true
example: true
required:
- name
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````