Skip to main content
POST
/
v2
/
organizations
/
folders
/
get
Get Folders
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

​
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
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}