Aıon

Documentation

Folders API Reference

Hierarchical folder management with breadcrumb navigation

Hierarchical Organization

Organize files into a desktop-like folder hierarchy. Supports nested folders, drag-and-drop organization, and breadcrumb navigation.

Folder Listing

GET/api/v2/folders

Get all folders as a flat list (build tree client-side using parent_id)

Response

{
  "folders": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Project Photos",
      "parent_id": null,
      "depth": 0,
      "file_count": 25,
      "subfolder_count": 3,
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    },
    {
      "id": "660f9500-f39c-52e5-b827-557766550111",
      "name": "Site Inspections",
      "parent_id": "550e8400-e29b-41d4-a716-446655440000",
      "depth": 1,
      "file_count": 10,
      "subfolder_count": 0,
      "created_at": "2025-01-15T10:05:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ]
}
GET/api/v2/folders/{folder_id}

Get folder contents including subfolders and file count

Request

// Query parameters:
?limit=50   // optional, default: 50, 1-100
&offset=0   // optional, default: 0

Response

{
  "folder": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Project Photos",
    "parent_id": null,
    "depth": 0,
    "file_count": 25,
    "subfolder_count": 3,
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  },
  "breadcrumbs": [
    {"id": "550e8400-e29b-41d4-a716-446655440000", "name": "Project Photos", "depth": 0}
  ],
  "subfolders": [
    {
      "id": "660f9500-f39c-52e5-b827-557766550111",
      "name": "Site Inspections",
      "parent_id": "550e8400-e29b-41d4-a716-446655440000",
      "depth": 1,
      "file_count": 10,
      "subfolder_count": 0,
      "created_at": "2025-01-15T10:05:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total_files": 25,
  "has_more_files": false
}
GET/api/v2/folders/{folder_id}/breadcrumbs

Get the ancestor chain for breadcrumb navigation

Response

{
  "breadcrumbs": [
    {"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Projects", "depth": 0},
    {"id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "2024", "depth": 1},
    {"id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "name": "Site A", "depth": 2}
  ]
}

Folder Operations

POST/api/v2/folders

Create a new folder. Returns 201 Created.

Request

{
  "name": "New Folder",
  "parent_id": "550e8400-e29b-41d4-a716-446655440000"  // null for root level
}

Response

{
  "id": "770a0600-a40d-63f6-c938-668877660222",
  "name": "New Folder",
  "parent_id": "550e8400-e29b-41d4-a716-446655440000",
  "depth": 1,
  "file_count": 0,
  "subfolder_count": 0,
  "created_at": "2025-01-15T10:30:00Z",
  "updated_at": "2025-01-15T10:30:00Z"
}
PATCH/api/v2/folders/{folder_id}

Rename an existing folder

Request

{
  "name": "Renamed Folder"
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Renamed Folder",
  "parent_id": null,
  "depth": 0,
  "file_count": 25,
  "subfolder_count": 3,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:35:00Z"
}
POST/api/v2/folders/{folder_id}/move

Move folder to a new parent (returns 422 if circular reference)

Request

{
  "new_parent_id": "770a0600-a40d-63f6-c938-668877660222"  // null to move to root
}

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Moved Folder",
  "parent_id": "770a0600-a40d-63f6-c938-668877660222",
  "depth": 2,
  "file_count": 25,
  "subfolder_count": 3,
  "created_at": "2025-01-15T10:00:00Z",
  "updated_at": "2025-01-15T10:35:00Z"
}
DELETE/api/v2/folders/{folder_id}

Delete a folder with configurable mode

Request

// Query parameters:
?mode=move_to_parent  // optional, default: move_to_parent, options: move_to_parent | delete_all

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "files_affected": 25,
  "subfolders_affected": 3,
  "mode": "move_to_parent"
}


// mode=move_to_parent: Files and subfolders move to parent
// mode=delete_all: Everything inside is permanently deleted

File Movement

POST/api/v2/folders/move-files

Move files to a folder (max 100 files per request)

Request

{
  "file_ids": ["550e8400-e29b-41d4-a716-446655440000", "660f9500-f39c-52e5-b827-557766550111", "770a0600-a40d-63f6-c938-668877660222"],
  "folder_id": "880b1700-b51e-74a7-da49-779988770333"  // null to move to root
}

Response

{
  "moved": 3,
  "total_requested": 3
}

Related

Files Reference

Managing files in folders