---
title: "Folders"
description: "Group projects in folders, and nest folders up to 5 levels deep."
---

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

# Folders

Folders group an organization's [projects](/organizations/projects) and other folders. They
only organize:

- A folder gives nobody access. No policy reaches a project through its folder, and moving a
  project or folder changes nobody's access.
- A project's resource name never includes its folder, so moving it changes no resource names.
- Folders nest at most 5 levels deep: a folder at the top of the organization is level 1.
- A folder's name is unique among the folders in the same place, ignoring case.
- Only an empty folder can be deleted.

## Identifiers

| Field | Example | Notes |
| --- | --- | --- |
| `id` | `0199a3c5-1b2c-7d3e-8f40-5a6b7c8d9e0f` | UUID. API paths and bodies use it. |
| `slug` | `fld_a1b2c3d4e5f6` | `fld_` and 12 lowercase letters and digits. Generated, unique and never changes. |
| `resourceName` | `ezgh::org_k3f9a0x2m7qp:fld_a1b2c3d4e5f6` | Names the folder in IAM policies, for the `folders.*` actions. |
| `name` | `Payments` | 1 to 100 characters. |
| `parentId` | `0199a3c5-…` or `null` | The folder it sits in; `null` at the top of the organization. |

A project's `folderId` is the folder it sits in, or `null` at the top of the organization.

The `ezgh` CLI accepts a folder's ID, slug, name, or path from the top of the organization,
such as `Engineering/Payments`.

## Permissions

| Action | Allows | Checked against |
| --- | --- | --- |
| `folders.list` | Listing folders. A list shows the folders you're allowed to list. | Folder |
| `folders.get` | Viewing a folder | Folder |
| `folders.create` | Creating folders | Organization |
| `folders.update` | Renaming and moving folders | Folder |
| `folders.delete` | Deleting empty folders | Folder |

`BasicAccess` and `ReadOnlyAccess` include `folders.list` and `folders.get`, so people can see the
folders their projects sit in. `ProjectsFullAccess` includes every `folders.*` action. Moving a
project needs only `projects.update` on the project.

## See folders and projects

### Console

Open **Projects**. Folders and projects show as one tree: expand a folder to see what it holds.
The filter matches folder and project names and IDs, and shows each match with the folders above
it.
### CLI

```sh
ezgh projects list --tree
```

```text
NAME                SLUG
Engineering/        fld_a1b2c3d4e5f6
  Payments/         fld_b2c3d4e5f6a1
    payments-prod   prj_c3d4e5f6a1b2
ops                 prj_d4e5f6a1b2c3
```

`ezgh folders list` lists folders one page at a time, with the folder each sits in.
### API

```sh
curl https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/folders \
  -H "Authorization: Bearer $EZGH_API_KEY"
```

The response is `{ "folders": [...], "nextCursor": ... }`, paged like other lists. See
[ListFolders](/orgs-api/folders/ListFolders/) and [GetFolder](/orgs-api/folders/GetFolder/).

## Create a folder

You need `folders.create`. Leave out the parent to create the folder at the top of the
organization.

### Console

1. Open **Projects** and click **Create folder**.
2. Enter a **Name** and choose a **Location**.
3. Click **Create folder**.
### CLI

```sh
ezgh folders create Engineering
ezgh folders create Payments --parent Engineering
```
### API

```sh
curl -X POST https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/folders \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "name": "Payments", "parentId": "'$PARENT_FOLDER_ID'" }'
```

The response is `201` with the folder. See [CreateFolder](/orgs-api/folders/CreateFolder/) and
[idempotency keys](/api/requests#idempotency-keys).

## Rename or move a folder

You need `folders.update` on the folder. A folder moves with everything in it. You can't move a
folder into itself or a folder inside it, or make the tree more than 5 levels deep.

### Console

Open the folder, then the **Settings** tab. Change its name and click **Rename**, or choose
another folder under **Location** and click **Move**.
### CLI

```sh
ezgh folders update Payments --name Billing
ezgh folders update Billing --parent Finance
ezgh folders update Billing --root
```

`--root` moves the folder to the top of the organization.
### API

```sh
curl -X PATCH https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/folders/$FOLDER_ID \
  -H "Authorization: Bearer $EZGH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "parentId": null }'
```

Send `name`, `parentId` or both. `"parentId": null` moves the folder to the top of the
organization. See [UpdateFolder](/orgs-api/folders/UpdateFolder/).

## Move a project into a folder

See [Move a project](/organizations/projects#move-a-project). To create a project in a folder,
see [Create a project](/organizations/create-a-project).

## Delete a folder

You need `folders.delete` on the folder. Only an empty folder can be deleted: move or delete its
projects and folders first.

### Console

Open the folder, then the **Settings** tab, and click **Delete folder**. It's disabled while the
folder holds anything you can see; a folder that holds anything can't be deleted
(`409 folder_not_empty`).
### CLI

```sh
ezgh folders delete Billing
```

The CLI asks for confirmation; `--yes` skips it.
### API

```sh
curl -X DELETE https://orgs.ezghcloud.com/v1/organizations/$ORG_ID/folders/$FOLDER_ID \
  -H "Authorization: Bearer $EZGH_API_KEY"
```

The response is `204`. See [DeleteFolder](/orgs-api/folders/DeleteFolder/).

## Errors

| Status | Code | When |
| --- | --- | --- |
| `404` | `not_found` | The folder or parent doesn't exist, was deleted, or belongs to another organization. |
| `409` | `folder_name_taken` | A folder with that name is already in the same place. |
| `409` | `folder_too_deep` | The folder would be more than 5 levels deep. |
| `409` | `folder_cycle` | The move would put a folder inside itself or a folder inside it. |
| `409` | `folder_not_empty` | The folder still holds a project or folder. |
| `409` | `quota_exceeded` | The organization has as many folders as its quota allows. |
| `412` | `precondition_failed` | An `If-Match` on a rename, move or delete doesn't match the folder's current `ETag`. See [conditional writes](/api/requests#conditional-writes). |

## Folder quota

An organization can have 100 folders by default. The quota is `organizations.folders.count`
(**Folders per organization**). It counts folders that exist: deleting one frees its slot. See
[Service quotas](/quotas).

Source: https://docs.ezghcloud.com/organizations/folders/index.mdx
