# Folders

Source: https://developers.leonai.io/docs/guides/folders/

Folders group your short links into a nested hierarchy so large libraries stay
organized. A link carries an optional `folderId`; folders can be nested up to **5 levels**
deep. Requires `links:read` / `links:write` scopes. Available on **all tiers**.

## Create a folder

```bash
curl -X POST https://api.short.leonai.io/api/v1/folders \
  -H "X-API-Key: $LEONAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 Campaigns",
    "parentId": null
  }'
```

Response (`201 Created`):

```json
{
  "success": true,
  "data": {
    "id": "fld_...",
    "name": "Q2 Campaigns",
    "parentId": null,
    "depth": 0,
    "linkCount": 0,
    "createdAt": "2026-07-11T12:00:00.000Z"
  }
}
```

Pass a `parentId` to nest a folder inside another. `REST: POST /api/v1/folders`.

## List, update, delete

```bash
# List your folders (tree)
curl https://api.short.leonai.io/api/v1/folders \
  -H "X-API-Key: $LEONAI_API_KEY"

# Rename or re-parent a folder
curl -X PATCH https://api.short.leonai.io/api/v1/folders/<folderId> \
  -H "X-API-Key: $LEONAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "name": "Q2 2026" }'

# Delete a folder
curl -X DELETE https://api.short.leonai.io/api/v1/folders/<folderId> \
  -H "X-API-Key: $LEONAI_API_KEY"
```

`REST: GET /api/v1/folders`, `PATCH /api/v1/folders/:id`, `DELETE /api/v1/folders/:id`.

:::note[Deleting is non-destructive]
Deleting a folder **keeps its links** — they are detached (their `folderId` becomes
`null`, moving them back to the root). Any child folders are **reparented** to the
deleted folder's parent, so nothing is lost.
:::

## Assign links to a folder

Move a set of links into a folder in one call:

```bash
curl -X PUT https://api.short.leonai.io/api/v1/folders/<folderId>/links \
  -H "X-API-Key: $LEONAI_API_KEY" -H "Content-Type: application/json" \
  -d '{ "linkIds": ["link_1", "link_2"] }'
```

`REST: PUT /api/v1/folders/:id/links`. This replaces each listed link's `folderId`.

## Filter links by folder

The [Links list endpoint](https://developers.leonai.io/docs/guides/links/#list-with-filtering--pagination) accepts a
`folderId` query parameter. Pass a folder id to list its links, or the literal `root` to
list links that aren't in any folder:

```bash
# Links inside a folder
curl "https://api.short.leonai.io/api/v1/links?folderId=<folderId>" \
  -H "X-API-Key: $LEONAI_API_KEY"

# Links not in any folder
curl "https://api.short.leonai.io/api/v1/links?folderId=root" \
  -H "X-API-Key: $LEONAI_API_KEY"
```

`REST: GET /api/v1/links?folderId={id|root}`.

## Error codes

| Status | When                                                           |
| ------ | -------------------------------------------------------------- |
| `400`  | Nesting would exceed the max depth of 5, or invalid `parentId` |
| `404`  | Folder (or a listed link) not found / not owned by you         |

## Related

- [Links](https://developers.leonai.io/docs/guides/links/) — the `folderId` field and `?folderId=` filter
- [API Reference](https://developers.leonai.io/docs/api-reference/) — the full OpenAPI spec and Swagger UI