Get Folders

POST /v2/organizations/folders/get

Get Folders

cURL

curl --request POST \
  --url https://api.velt.dev/v2/organizations/folders/get \
  --header 'Content-Type: application/json' \
  --header 'x-velt-api-key: <x-velt-api-key>' \
  --header 'x-velt-auth-token: <x-velt-auth-token>' \
  --data '
{
  "data": {
    "organizationId": "<string>",
    "folderId": "<string>",
    "maxDepth": 123
  }
}
'

{
  "result": {
    "status": "success",
    "message": "Folder(s) retrieved successfully.",
    "data": [
      {
        "folderId": "folder1",
        "folderName": "folder1",
        "parentFolderId": "root",
        "apiKey": "yourApiKey",
        "organizationId": "yourOrganizationId",
        "createdAt": 1758876118035,
        "lastUpdated": 1758876118035,
        "ancestors": ["root"],
        "accessType": "public",
        "inheritAccessFromParent": false,
        "subFolders": [
          {
            "folderId": "folder1.1",
            "folderName": "folder1.1",
            "parentFolderId": "folder1",
            "apiKey": "yourApiKey",
            "organizationId": "yourOrganizationId",
            "createdAt": 1758876239180,
            "lastUpdated": 1758876239180,
            "ancestors": ["root", "folder1"],
            "accessType": "public",
            "inheritAccessFromParent": true,
            "subFolders": [
              {
                "folderId": "folder1.1.1",
                "folderName": "folder1.1.1",
                "apiKey": "yourApiKey",
                "organizationId": "yourOrganizationId",
                "parentFolderId": "folder1.1",
                "createdAt": 1758883072416,
                "lastUpdated": 1758883072416,
                "ancestors": ["root", "folder1", "folder1.1"],
                "accessType": "public",
                "inheritAccessFromParent": false,
                "subFolders": [
                  {
                    "folderId": "folder1.1.1.1",
                    "folderName": "folder1.1.1.1",
                    "parentFolderId": "folder1.1.1",
                    "apiKey": "yourApiKey",
                    "organizationId": "yourOrganizationId",
                    "createdAt": 1758906266851,
                    "lastUpdated": 1758906266851,
                    "ancestors": ["root", "folder1", "folder1.1", "folder1.1.1"],
                    "accessType": "public",
                    "inheritAccessFromParent": true
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Use this API to retrieve the given folder’s metadata and its subfolders. You can retrieve nested subfolders at any depth level using the maxDepth parameter. The response includes an ancestors array showing the parent hierarchy and an inheritAccessFromParent field indicating whether access is inherited.

Prior to using this API, you must:

• Enable advanced queries option in the console
• Deploy v4 series of the Velt SDK.

Endpoint

POST https://api.velt.dev/v2/organizations/folders/get

Headers

x-velt-api-key · string · required

Your API key.

x-velt-auth-token · string · required

Your Auth Token.

Body

Params

data · object · required

Show properties

organizationId · string · required

Organization ID

folderId · string

Folder ID to retrieve a specific folder and its subfolders. If not provided, all folders in the organization will be retrieved.

maxDepth · number

Maximum depth level for retrieving nested subfolders. Allows you to retrieve subfolders at any depth level. If not provided, only immediate subfolders are retrieved.

Example Requests

1. Get all folders in organization

{
  "data": {
    "organizationId": "yourOrganizationId"
  }
}

2. Get specific folder in an organization

{
  "data": {
    "organizationId": "yourOrganizationId",
    "folderId": "yourFolderId"
  }
}

3. Get folder with nested subfolders at specific depth

Use the maxDepth parameter to retrieve nested subfolders at any depth level. The response includes an ancestors array showing the parent hierarchy and an inheritAccessFromParent field indicating whether access is inherited.

{
  "data": {
    "organizationId": "yourOrganizationId",
    "folderId": "yourFolderId",
    "maxDepth": 3
  }
}

Response

Success Response for All Folders

{
  "result": {
    "status": "success",
    "message": "Folders retrieved successfully.",
    "data": [
      {
        "folderId": "folderId1",
        "folderName": "Folder 1",
        "organizationId": "yourOrganizationId",
        "parentFolderId": "root",
        "apiKey": "yourApiKey",
        "createdAt": 1738695615706,
        "lastUpdated": 1738696287859,
        "ancestors": ["root"],
        "accessType": "public",
        "inheritAccessFromParent": false
      },
      {
        "folderId": "folderId2",
        "folderName": "Folder 2",
        "organizationId": "yourOrganizationId",
        "parentFolderId": "root",
        "apiKey": "yourApiKey",
        "createdAt": 1738695077691,
        "lastUpdated": 1738695077691,
        "ancestors": ["root"],
        "accessType": "restricted",
        "inheritAccessFromParent": true
      }
    ]
  }
}

Success Response for Specific Folder

{
  "result": {
    "status": "success",
    "message": "Folder(s) retrieved successfully.",
    "data": [
      {
        "folderId": "folderId1",
        "folderName": "Folder 1",
        "organizationId": "yourOrganizationId",
        "parentFolderId": "root",
        "apiKey": "yourApiKey",
        "createdAt": 1738695077691,
        "lastUpdated": 1738695077691,
        "ancestors": ["root"],
        "accessType": "public",
        "inheritAccessFromParent": false,
        "subFolders": [
          {
            "folderId": "childFolderId1",
            "folderName": "Child Folder 1",
            "organizationId": "yourOrganizationId",
            "parentFolderId": "folderId1",
            "apiKey": "yourApiKey",
            "createdAt": 1738695615706,
            "lastUpdated": 1738698727591,
            "ancestors": ["root", "folderId1"],
            "accessType": "public",
            "inheritAccessFromParent": true
          }
        ]
      }
    ]
  }
}

Success Response with maxDepth

When using maxDepth, the response includes deeply nested subfolders. Each folder includes an ancestors array showing its full parent hierarchy and an inheritAccessFromParent field indicating whether it inherits access permissions from its parent.

{
  "result": {
    "status": "success",
    "message": "Folder(s) retrieved successfully.",
    "data": [
      {
        "folderId": "folder1",
        "folderName": "folder1",
        "parentFolderId": "root",
        "apiKey": "yourApiKey",
        "organizationId": "yourOrganizationId",
        "createdAt": 1758876118035,
        "lastUpdated": 1758876118035,
        "ancestors": ["root"],
        "accessType": "public",
        "inheritAccessFromParent": false,
        "subFolders": [
          {
            "folderId": "folder1.1",
            "folderName": "folder1.1",
            "parentFolderId": "folder1",
            "apiKey": "yourApiKey",
            "organizationId": "yourOrganizationId",
            "createdAt": 1758876239180,
            "lastUpdated": 1758876239180,
            "ancestors": ["root", "folder1"],
            "accessType": "public",
            "inheritAccessFromParent": true,
            "subFolders": [
              {
                "folderId": "folder1.1.1",
                "folderName": "folder1.1.1",
                "apiKey": "yourApiKey",
                "organizationId": "yourOrganizationId",
                "parentFolderId": "folder1.1",
                "createdAt": 1758883072416,
                "lastUpdated": 1758883072416,
                "ancestors": ["root", "folder1", "folder1.1"],
                "accessType": "public",
                "inheritAccessFromParent": false,
                "subFolders": [
                  {
                    "folderId": "folder1.1.1.1",
                    "folderName": "folder1.1.1.1",
                    "parentFolderId": "folder1.1.1",
                    "apiKey": "yourApiKey",
                    "organizationId": "yourOrganizationId",
                    "createdAt": 1758906266851,
                    "lastUpdated": 1758906266851,
                    "ancestors": ["root", "folder1", "folder1.1", "folder1.1.1"],
                    "accessType": "public",
                    "inheritAccessFromParent": true
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Failure Response

{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}

{
  "result": {
    "status": "success",
    "message": "Folder(s) retrieved successfully.",
    "data": [
      {
        "folderId": "folder1",
        "folderName": "folder1",
        "parentFolderId": "root",
        "apiKey": "yourApiKey",
        "organizationId": "yourOrganizationId",
        "createdAt": 1758876118035,
        "lastUpdated": 1758876118035,
        "ancestors": ["root"],
        "accessType": "public",
        "inheritAccessFromParent": false,
        "subFolders": [
          {
            "folderId": "folder1.1",
            "folderName": "folder1.1",
            "parentFolderId": "folder1",
            "apiKey": "yourApiKey",
            "organizationId": "yourOrganizationId",
            "createdAt": 1758876239180,
            "lastUpdated": 1758876239180,
            "ancestors": ["root", "folder1"],
            "accessType": "public",
            "inheritAccessFromParent": true,
            "subFolders": [
              {
                "folderId": "folder1.1.1",
                "folderName": "folder1.1.1",
                "apiKey": "yourApiKey",
                "organizationId": "yourOrganizationId",
                "parentFolderId": "folder1.1",
                "createdAt": 1758883072416,
                "lastUpdated": 1758883072416,
                "ancestors": ["root", "folder1", "folder1.1"],
                "accessType": "public",
                "inheritAccessFromParent": false,
                "subFolders": [
                  {
                    "folderId": "folder1.1.1.1",
                    "folderName": "folder1.1.1.1",
                    "parentFolderId": "folder1.1.1",
                    "apiKey": "yourApiKey",
                    "organizationId": "yourOrganizationId",
                    "createdAt": 1758906266851,
                    "lastUpdated": 1758906266851,
                    "ancestors": ["root", "folder1", "folder1.1", "folder1.1.1"],
                    "accessType": "public",
                    "inheritAccessFromParent": true
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}