> ## Documentation Index
> Fetch the complete documentation index at: https://velt-mintlify-e6426361.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Get folders (v2)

> Retrieve folders within an organization filtered by IDs or parent using the Velt v2 REST API to render navigation trees and content browsers in your app.

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.

<Warning>
  Prior to using this API, you must:

  * Enable advanced queries option in [the console](https://console.velt.dev/dashboard/config/appconfig)
  * Deploy v4 series of the Velt SDK.
</Warning>

# Endpoint

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

# Headers

<ParamField header="x-velt-api-key" type="string" required>
  Your API key.
</ParamField>

<ParamField header="x-velt-auth-token" type="string" required>
  Your [Auth Token](/security/auth-tokens).
</ParamField>

# Body

#### Params

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="organizationId" type="string" required>
      Organization ID
    </ParamField>

    <ParamField body="folderId" type="string">
      Folder ID to retrieve a specific folder and its subfolders. If not provided, all folders in the organization will be retrieved.
    </ParamField>

    <ParamField body="maxDepth" type="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.
    </ParamField>
  </Expandable>
</ParamField>

## **Example Requests**

#### 1. Get all folders in organization

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId"
  }
}
```

#### 2. Get specific folder in an organization

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "folderId": "yourFolderId"
  }
}
```

#### 3. Get folder with nested subfolders at specific depth

<Note>
  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.
</Note>

```JSON theme={null}
{
  "data": {
    "organizationId": "yourOrganizationId",
    "folderId": "yourFolderId",
    "maxDepth": 3
  }
}
```

# Response

#### Success Response for All Folders

```JSON theme={null}
{
  "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

```JSON theme={null}
{
  "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

<Note>
  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.
</Note>

```JSON theme={null}
{
  "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

```JSON theme={null}
{
  "error": {
    "message": "ERROR_MESSAGE",
    "status": "INVALID_ARGUMENT"
  }
}
```

<ResponseExample>
  ```js theme={null}
  {
    "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
                    }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  }
  ```
</ResponseExample>