Create a new directory (folder)

POST

directories

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));

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

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

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

Request · Response · Guide: Folders

More details

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

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

directory

object

Show child attributes

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));

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

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

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

{
  "type": "https://errors.file.ai/validation-failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/v1/files/upload",
  "code": "VALIDATION_FAILED",
  "requestId": "0f1c8e03-978e-40d5-bc93-6894a57f9324",
  "errors": [
    {
      "code": "REQUIRED",
      "detail": "must not be empty",
      "pointer": "#/fileName",
      "parameter": "limit"
    }
  ],
  "message": "Validation failed",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "retryAfter": 42
}

Get started

Endpoints

Create a new directory (folder)

Authorizations

Headers

Body

Response