Create a new directory

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/directories \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Directory 1",
  "description": "Description",
  "parentId": "649e2d2d2d2d2d2d2d2d2d2d",
  "isActive": true
}
'

{
  "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"
  }
}

Endpoints

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

POST

prod

directories

Create a new directory

curl --request POST \
  --url https://api.orion.file.ai/prod/v1/directories \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "name": "Directory 1",
  "description": "Description",
  "parentId": "649e2d2d2d2d2d2d2d2d2d2d",
  "isActive": true
}
'

{
  "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"
  }
}

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

File Organization

Create folders to organize uploaded files by category, project, or type

Nested Structure

Build hierarchical folder structures with parent-child relationships

Workflow Automation

Programmatically create folders as part of automated workflows

Team Collaboration

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

Root Level (depth: 0)

Directories created without a parentId are placed at the root level with depth: 0.

Subdirectories (depth: 1+)

When you provide a parentId, the system automatically calculates the depth by incrementing the parent’s depth by 1.

Depth Limits

The system enforces a maximum depth limit (default: 1 level). Attempting to create directories beyond this limit will result in a 400 error.

Authorizations

x-api-key

string

header

required

API key for authentication

Body

application/json

name

string

required

Directory name

Example:

"Directory 1"

description

string

Directory description

Example:

"Description"

parentId

string

Parent directory id

Example:

"649e2d2d2d2d2d2d2d2d2d2d"

isActive

boolean

default:true

Is active

Example:

true

Response

The directory is created

success

boolean

​Use Cases

File Organization

Nested Structure

Workflow Automation

Team Collaboration

​Request Parameters

​Request Body

​Directory Properties

​Automatic Fields

​Depth Calculation

Authorizations

Body

Response

Use Cases

Request Parameters

Request Body

Directory Properties

Automatic Fields

Depth Calculation