Folders API

The Folders API allows you to organize packages into a hierarchical folder structure.

Overview

Folders provide a way to organize packages within a vault. Folders can be nested to create a hierarchical structure that mirrors your business organization.

Key concepts: A Folder is a container for organizing packages. Hierarchy means folders can contain other folders (up to 10 levels deep). Root Level is the top level of the vault. Path is an internal GUID-based path used for hierarchy queries (root folders have path /).

Required scopes

Scope	Description
`folders:read`	View folder structure
`folders:write`	Create, modify, and delete folders
`folders`	Full access (read + write)

Constraints

Constraint	Limit
Maximum depth	10 levels
Name uniqueness	Unique within parent folder

List Folders

Retrieve folders in the vault.

GET /api/vault/folders

Required scope: folders:read.

Query parameters

Parameter	Type	Required	Default	Description
`parentFolderId`	guid	No	—	Filter by parent folder
`rootOnly`	boolean	No	false	Return only root-level folders
`includeDescendants`	boolean	No	false	Include all descendants of parent

Response (200 OK)

[
  {
    "id": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
    "organizationId": "1fa85f64-5717-4562-b3fc-2c963f66afa6",
    "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
    "parentFolderId": null,
    "name": "2024",
    "numberOfPackages": 0,
    "numberOfSubfolders": 4,
    "depth": 0,
    "path": "/"
  },
  {
    "id": "8fa85f64-5717-4562-b3fc-2c963f66afa6",
    "organizationId": "1fa85f64-5717-4562-b3fc-2c963f66afa6",
    "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
    "parentFolderId": null,
    "name": "Archive",
    "numberOfPackages": 150,
    "numberOfSubfolders": 0,
    "depth": 0,
    "path": "/"
  }
]

Get Folder

Retrieve details for a specific folder including breadcrumbs and child folders.

GET /api/vault/folders/{id}

Required scope: folders:read. Path parameter id (guid, required).

Response (200 OK)

{
  "id": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
  "organizationId": "1fa85f64-5717-4562-b3fc-2c963f66afa6",
  "vaultId": "2fa85f64-5717-4562-b3fc-2c963f66afa6",
  "parentFolderId": null,
  "name": "2024",
  "numberOfPackages": 0,
  "numberOfSubfolders": 4,
  "depth": 0,
  "path": "/",
  "breadcrumbs": [],
  "childFolders": [
    {
      "id": "9fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Q1",
      "numberOfPackages": 45,
      "numberOfSubfolders": 3,
      "depth": 1,
      "path": "/7fa85f64-5717-4562-b3fc-2c963f66afa6/"
    },
    {
      "id": "afa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Q2",
      "numberOfPackages": 52,
      "numberOfSubfolders": 3,
      "depth": 1,
      "path": "/7fa85f64-5717-4562-b3fc-2c963f66afa6/"
    }
  ]
}

Error responses: 404 — Folder not found.

Create Folder

Create a new folder.

POST /api/vault/folders

Required scope: folders:write.

Request body

Field	Type	Required	Description
`name`	string	Yes	Folder name
`parentFolderId`	guid	No	Parent folder ID (null for root folder)

Response (200 OK): Returns the created VaultFolderViewModel.

Error responses: 400 — Parent folder is at maximum depth; 409 — A folder with the same name already exists in this location; 404 — Parent folder not found.

Update Folder

Rename a folder.

PUT /api/vault/folders/{folderId}

Required scope: folders:write. Path parameter folderId (guid, required).

Request body: name (string, required) — New folder name.

Response (200 OK): Returns the updated VaultFolderViewModel.

Error responses: 400 — Folder with same name already exists; 404 — Folder not found.

Move Folder

Move a folder to a new parent location.

POST /api/vault/folders/move

Required scope: folders:write.

Request body

Field	Type	Required	Description
`folderId`	guid	Yes	Folder to move
`targetParentFolderId`	guid	No	New parent folder (null to move to root)

Response (200 OK): Returns the moved VaultFolderViewModel with updated path and depth.

Error responses: 400 — Cannot move folder into itself or its children; 400 — Move would exceed maximum depth (10 levels); 409 — A folder with the same name already exists in this location; 404 — Folder or target parent not found.

Delete Folder

Delete an empty folder.

DELETE /api/vault/folders/{id}

Required scope: folders:write. Path parameter id (guid, required).

Response (204 No Content). Note: Folders must be empty (no packages and no subfolders) before they can be deleted.

Error responses: 400 — Folder contains packages; 400 — Folder contains subfolders; 404 — Folder not found.

Response models (Folders API)

VaultFolderViewModel

Field	Type	Description
`id`	guid	Unique identifier
`organizationId`	guid	Organization ID
`vaultId`	guid	Vault ID
`parentFolderId`	guid	Parent folder ID (null for root)
`name`	string	Folder name
`numberOfPackages`	integer	Number of packages in folder
`numberOfSubfolders`	integer	Number of child folders
`depth`	integer	Nesting level (0 = root)
`path`	string	Internal GUID-based path (“/” for root)

VaultFolderDetailViewModel

Extends VaultFolderViewModel with:

Field	Type	Description
`breadcrumbs`	array	Ancestor folders (`id`, `name`)
`childFolders`	array	Direct child `VaultFolderViewModel`s

BreadcrumbItem

Field	Type	Description
`id`	guid	Folder ID
`name`	string	Folder name

Next: Workflows API.