Scopix

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)

Request

json
// Query parameters:
?project_id=uuid  // optional, filter to folders in a specific project workspace

Response

json
{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Site Photos",
      "parent_id": null,
      "project_id": "aa000000-0000-0000-0000-000000000001",
      "depth": 0,
      "file_count": 25,
      "subfolder_count": 3,
      "pipeline_id": null,
      "pipeline_name": null,
      "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",
      "project_id": "aa000000-0000-0000-0000-000000000001",
      "depth": 1,
      "file_count": 10,
      "subfolder_count": 0,
      "pipeline_id": null,
      "pipeline_name": null,
      "created_at": "2025-01-15T10:05:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total_count": 2
}
GET/api/v2/folders/{folder_id}

Get folder contents including subfolders and file count

Request

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

Response

json
{
  "folder": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Project Photos",
    "parent_id": null,
    "project_id": "aa000000-0000-0000-0000-000000000001",
    "depth": 0,
    "file_count": 25,
    "subfolder_count": 3,
    "pipeline_id": null,
    "pipeline_name": null,
    "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",
      "project_id": "aa000000-0000-0000-0000-000000000001",
      "depth": 1,
      "file_count": 10,
      "subfolder_count": 0,
      "pipeline_id": null,
      "pipeline_name": null,
      "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

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

json
{
  "name": "New Folder",
  "parent_id": "550e8400-e29b-41d4-a716-446655440000",  // null for root level
  "project_id": "aa000000-0000-0000-0000-000000000001"   // optional, defaults to Default project
}


// project_id resolution order:
//   1. Explicit project_id in this request (takes priority)
//   2. Inherited from the parent folder's project (if parent_id is set and project_id is omitted)
//   3. Default project (if neither project_id nor parent_id resolves a project)

Response

json
{
  "id": "770a0600-a40d-63f6-c938-668877660222",
  "name": "New Folder",
  "parent_id": "550e8400-e29b-41d4-a716-446655440000",
  "project_id": "aa000000-0000-0000-0000-000000000001",
  "depth": 1,
  "file_count": 0,
  "subfolder_count": 0,
  "pipeline_id": null,
  "pipeline_name": null,
  "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

json
{
  "name": "Renamed Folder"
}

Response

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Renamed Folder",
  "parent_id": null,
  "project_id": "aa000000-0000-0000-0000-000000000001",
  "depth": 0,
  "file_count": 25,
  "subfolder_count": 3,
  "pipeline_id": null,
  "pipeline_name": null,
  "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

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

Response

json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Moved Folder",
  "parent_id": "770a0600-a40d-63f6-c938-668877660222",
  "project_id": "aa000000-0000-0000-0000-000000000001",
  "depth": 2,
  "file_count": 25,
  "subfolder_count": 3,
  "pipeline_id": null,
  "pipeline_name": null,
  "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

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

Response

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

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

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

Related

Projects Reference

Create and manage project workspaces

Files Reference

Managing files in folders