> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sundaypyjamas.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Folders & Tree

> Create and rename folders, and browse the folder tree

## Create Folder

```http theme={null}
POST /api/v1/workspaces/{workspaceId}/storage/folders
```

<ParamField body="folderPath" type="string" required />

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "created": true,
    "folder": { "id": "fold_1", "name": "archive", "path": "/archive" }
  }
  ```
</ResponseExample>

***

## Rename Folder

```http theme={null}
PATCH /api/v1/workspaces/{workspaceId}/storage/folders
```

<ParamField body="folderPath" type="string" required />

<ParamField body="newName" type="string" required />

***

## Browse Path / Tree

```http theme={null}
GET /api/v1/workspaces/{workspaceId}/storage/path
```

<ParamField query="folderPath" type="string" default="/">Alias: `path`.</ParamField>

<ParamField query="tree" type="string">
  `1` — return just the list of folder paths. `full` — return the entire tree (folders + files).
</ParamField>

<ParamField query="mode" type="string">`tree` is an alias for `tree=1`.</ParamField>

### Response shapes

<Tabs>
  <Tab title="Default (folder contents)">
    ```json theme={null}
    {
      "path": "/archive",
      "folders": [ { "id": "fold_2", "name": "2026", "path": "/archive/2026" } ],
      "files": [ /* StorageFile[] — see Files */ ]
    }
    ```
  </Tab>

  <Tab title="tree=1 (paths only)">
    ```json theme={null}
    { "paths": ["/", "/archive", "/archive/2026", "/uploads"] }
    ```
  </Tab>

  <Tab title="tree=full">
    ```json theme={null}
    {
      "folders": [ /* all folders */ ],
      "files": [ /* all files */ ]
    }
    ```
  </Tab>
</Tabs>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://suite.sundaypyjamas.com/api/v1/workspaces/ws_123/storage/path?folderPath=/archive" \
    -H "Authorization: Bearer spj_ai_your_api_key_here"
  ```
</RequestExample>

## Errors

| Status | Error                                                                              |
| ------ | ---------------------------------------------------------------------------------- |
| 400    | `folderPath is required` (Create) / `folderPath and newName are required` (Rename) |
| 401    | `Unauthorized`                                                                     |