Create a new directory (folder)

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
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/directories"

payload = {
    "name": "Directory 1",
    "description": "Description",
    "parentId": "649e2d2d2d2d2d2d2d2d2d2d",
    "isActive": True
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Directory 1',
    description: 'Description',
    parentId: '649e2d2d2d2d2d2d2d2d2d2d',
    isActive: true
  })
};

fetch('https://api.orion.file.ai/prod/v1/directories', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orion.file.ai/prod/v1/directories",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Directory 1',
    'description' => 'Description',
    'parentId' => '649e2d2d2d2d2d2d2d2d2d2d',
    'isActive' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.orion.file.ai/prod/v1/directories"

	payload := strings.NewReader("{\n  \"name\": \"Directory 1\",\n  \"description\": \"Description\",\n  \"parentId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"isActive\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.orion.file.ai/prod/v1/directories")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Directory 1\",\n  \"description\": \"Description\",\n  \"parentId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"isActive\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orion.file.ai/prod/v1/directories")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Directory 1\",\n  \"description\": \"Description\",\n  \"parentId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"isActive\": true\n}"

response = http.request(request)
puts response.read_body

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

Endpoints

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

POST

prod

directories

Create a new directory (folder)

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
}
'

import requests

url = "https://api.orion.file.ai/prod/v1/directories"

payload = {
    "name": "Directory 1",
    "description": "Description",
    "parentId": "649e2d2d2d2d2d2d2d2d2d2d",
    "isActive": True
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: 'Directory 1',
    description: 'Description',
    parentId: '649e2d2d2d2d2d2d2d2d2d2d',
    isActive: true
  })
};

fetch('https://api.orion.file.ai/prod/v1/directories', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.orion.file.ai/prod/v1/directories",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => 'Directory 1',
    'description' => 'Description',
    'parentId' => '649e2d2d2d2d2d2d2d2d2d2d',
    'isActive' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.orion.file.ai/prod/v1/directories"

	payload := strings.NewReader("{\n  \"name\": \"Directory 1\",\n  \"description\": \"Description\",\n  \"parentId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"isActive\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("x-api-key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.orion.file.ai/prod/v1/directories")
  .header("x-api-key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"Directory 1\",\n  \"description\": \"Description\",\n  \"parentId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"isActive\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.orion.file.ai/prod/v1/directories")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["x-api-key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"Directory 1\",\n  \"description\": \"Description\",\n  \"parentId\": \"649e2d2d2d2d2d2d2d2d2d2d\",\n  \"isActive\": true\n}"

response = http.request(request)
puts response.read_body

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

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.

This endpoint accepts an optional Idempotency-Key request header so a retry cannot apply the change twice. See Idempotent requests.

Authorizations

x-api-key

string

header

required

API key for authentication

Headers

Idempotency-Key

string

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.

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

fileAI API

Key Functions

Endpoints

Create a new directory (folder)

Use Cases

File Organization

Nested Structure

Workflow Automation

Team Collaboration

Request Parameters

Request Body

Directory Properties

Automatic Fields

Depth Calculation

Authorizations

Headers

Body

Response

​Use Cases

File Organization

Nested Structure

Workflow Automation

Team Collaboration

​Request Parameters

​Request Body

​Directory Properties

​Automatic Fields

​Depth Calculation

Authorizations

Headers

Body

Response

Use Cases

Request Parameters

Request Body

Directory Properties

Automatic Fields

Depth Calculation