> ## 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 (folder)
> 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.
This endpoint accepts an optional `Idempotency-Key` request header so a retry
cannot apply the change twice. See
[Idempotent requests](/docs-api/api-idempotency).
## 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
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:
post:
tags:
- Public API V1
summary: Create a new directory (folder)
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:
- name: Idempotency-Key
in: header
description: >-
Optional opaque key (max 255 chars, UUIDv4 recommended) making this
request idempotent for 24h: a retry with the same key and body
replays the original response with Idempotent-Replayed: true.
required: false
schema:
type: string
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
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
items:
type: string
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/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
example:
type: https://errors.file.ai/bad-request
title: Bad request
status: 400
detail: Directory depth limit exceeded
instance: /v1/{route}
code: BAD_REQUEST
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Directory depth limit exceeded
error: Bad Request
statusCode: 400
'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: Invalid name | Invalid parentId
content:
application/problem+json:
schema:
$ref: '#/components/schemas/ProblemDetailsDto'
examples:
Invalid name:
summary: Invalid name
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid name.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid name.
error: Unprocessable Entity
statusCode: 422
Invalid parentId:
summary: Invalid parentId
value:
type: https://errors.file.ai/validation-failed
title: Validation failed
status: 422
detail: Invalid parentId.
instance: /v1/{route}
code: VALIDATION_FAILED
requestId: 0f1c8e03-978e-40d5-bc93-6894a57f9324
errors: []
message: Invalid parentId.
error: Unprocessable Entity
statusCode: 422
'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:
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
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
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
securitySchemes:
x-api-key:
type: apiKey
in: header
name: x-api-key
description: API key for authentication
````