# Folders

## List folders

This endpoint makes an HTTP GET request to retrieve a list of projects from a level of a folder's tree.

### Request

* Method: GET
* Endpoint: `https://api.thebrief.ai/v1/folders`
* Query Parameters:
  * `projectId` (integer, required): The projectId in which will search the folders
  * `parentId`(integer, optional): Will search subfolders in folder with id equal to parentId value

```bash
curl --location 'https://api.thebrief.ai/v1/folders' \
--header 'Authorization: Bearer eyJh...'
```

### Response

Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure:

JSON

```json
{
    "response": {
        "folders": [
            {
                "id": 111111,
                "name": "Folder Name 1",
                "parentId": null,
                "createdByUser": {
                    "id": 22222,
                    "name": "User Name 1"
                },
                "isParent": null,
                "updatedAt": "2024-12-04T08:59:00.509Z",
                "createdAt": "2024-09-30T07:11:45.948Z",
                "updatedByUser": {
                    "id": 33333,
                    "name": "User name 2"
                }
            },
            {
                "id": 333333,
                "name": "Folder Name 2",
                "parentId": null,
                "createdByUser": {
                    "id": 44444,
                    "name": "User Name 3"
                },
                "isParent": null,
                "updatedAt": "2024-12-03T15:21:53.010Z",
                "createdAt": "2024-12-03T14:38:17.513Z",
                "updatedByUser": {
                    "id": 44444,
                    "name": "User Name 4"
                }
            },
            
        "path": [],
        "rootFolderHash": null
    }
}
```

If the parentId is not null in the request the JSON response will contain data about the path to that folder 

```json
{
    "response": {
        "folders": [
            {
                "id": 111111,
                "name": "Folder Second Level,
                "parentId": 222222,
                "createdByUser": {
                    "id": 111111,
                    "name": "User Name 1"
                },
                "isParent": null,
                "updatedAt": "2024-11-15T12:10:29.480Z",
                "createdAt": "2024-11-13T13:51:19.973Z",
                "updatedByUser": {
                    "id": 22222,
                    "name": "User Name 2"
                }
            }
        ],
        "path": [
            {
                "name": "Main Level Folder",
                "id": 333333,
                "shared": false,
                "publicStatus": "public",
                "publicHash": "dgnop4kkelmj",
                "template": false
            }
        ],
        "rootFolderHash": null
    }
}
```

## Create Folder

This endpoint allows you to create a new folder.

### Request

* Method: POST
* Endpoint: `https://api.thebrief.ai/v1/folders`
* Body:
  * `name` (string, required): The name of the folder.
  * `projectId` (integer, required): The ID of the project in which user will create the folder.
  * `parentId` (integer, optional): The ID of the folder in within the user will create the new folder.

### Response

Upon a successful execution, the response will have a status code of 200 and a JSON content type. The response body will contain the following structure:

JSON

```json
{
    "response": {
        "folder": {
            "id": 111111,
            "name": "Subfolder 1",
            "projectId": 358029,
            "parentId": 717554,
            "createdByUser": {
                "id": 111111,
                "name": "User Name 1"
            },
            "updatedByUser": {
                "id": 111111,
                "name": "User Name 1"
            },
            "createdAt": "2024-12-04T18:21:54.636Z",
            "updatedAt": "2024-12-04T18:21:54.636Z",
            "isParent": null
        }
    }
}
```

## Delete Folder

This endpoint allows you to delete a folder.

### Request

* Method: DELETE
* Endpoint: `https://api.thebrief.ai/v1/folders`
* Body:
  * `folderId` (integer, required): The ID of the folder you want to be deleted.

{% code title="Request example" %}

```bash
curl --location --request DELETE 'https://api.thebrief.ai/v1/folders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhdXRob3JpemF0aW9uIjoiQmVhcmVyIGV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpwWVhRaU9qRTJPREV4TVRVMU56YzVPRElzSW1Oc2FXVnVkRWxrSWpvaU16QmpaalJsTldRdE1XRmxOQzAwT1RrNExUa3lNV010TVdVMU5qZzJOemd4WW1VeEluMC56WlRDX0ZHZW5FdklRZHhZTlk1cW9OWnlxSEdEOUYtTUtpNm1uV0h6V1NvIiwiYWxnIjoiSFMyNTYifQ.eyJjbGllbnRJZCI6IjZhMzhlYTk3LTEyOWQtNDE3MS04NTljLTU1MzVjOWYzZTRlMSJ9.gWvLWJSqk0bSO78t5xxdYcR08KHAyvQtKCxd0mnlK5U' \
--data '{
    "folderId": 123456
}'
```

{% endcode %}

### Response

```
{
    "response": 
    {
        "status": "success" 
    }
}
```

## Update Folder

This endpoint allows you to update a folder's name.

### Request

* Method: PUT
* Endpoint: `https://api.thebrief.ai/v1/folders`
* Body:
  * `name` (string, required): The new name of the folder you want to update.
  * `folderId` (integer, required): The ID of the folder you want to be updated.

{% code title="Request example" %}

```bash
curl --location --request PUT 'https://api.thebrief.ai/v1/folders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhdXRob3JpemF0aW9uIjoiQmVhcmVyIGV5SmhiR2NpT2lKSVV6STFOaUlzSW5SNWNDSTZJa3BYVkNKOS5leUpwWVhRaU9qRTJPREV4TVRVMU56YzVPRElzSW1Oc2FXVnVkRWxrSWpvaU16QmpaalJsTldRdE1XRmxOQzAwT1RrNExUa3lNV010TVdVMU5qZzJOemd4WW1VeEluMC56WlRDX0ZHZW5FdklRZHhZTlk1cW9OWnlxSEdEOUYtTUtpNm1uV0h6V1NvIiwiYWxnIjoiSFMyNTYifQ.eyJjbGllbnRJZCI6IjZhMzhlYTk3LTEyOWQtNDE3MS04NTljLTU1MzVjOWYzZTRlMSJ9.gWvLWJSqk0bSO78t5xxdYcR08KHAyvQtKCxd0mnlK5U' \
--data '{
    "name": "New folder name"
    "folderId": 123456
}'
```

{% endcode %}

### Response

```
{
    "response": {
        "folder": {
            "id": 123456,
            "name": "New folder name",
            "projectId": 567890,
            "parentId": null,
            "createdByUser": {
                "id": 111111,
                "name": "User Name 1"
            },
            "updatedByUser": {
                "id": 111111,
                "name": "User Name 1"
            },
            "createdAt": "2024-12-03T14:38:17.513Z",
            "updatedAt": "2024-12-03T15:21:53.010Z",
            "isParent": null
        }
    }
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.thebrief.ai/public-api/rest-api/folders.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.