---
title: "Directories API Reference | Linkbreakers"
description: "Folders for your links: directories hold links and other directories, as a tree."
canonical: "https://linkbreakers.com/help/api/directories"
---

# Directories

Folders for your links: directories hold links and other directories, as a tree.

6 entries on this page

## The directory object

A folder of links and other directories within a workspace.

`createdAt` string (date-time) 

Read-only

When the directory was created

`id` string

The unique identifier of the directory (UUID)

`name` string

The name of the directory

`parentDirectoryId` string

The ID of the parent directory (UUID) If not set, the directory is at the root level.

`path` string 

Read-only

Full hierarchical path separated by slashes, computed server-side

`updatedAt` string (date-time) 

Read-only

When the directory was last updated

`workspaceId` string

The workspace ID the directory belongs to (UUID)

Example directory

```json
{
  "createdAt": "2026-03-14T09:30:00Z",
  "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "name": "Table cards",
  "parentDirectoryId": "4e6a8c0d-2f1b-4d3e-9a5c-7b9d1f3e5a28",
  "path": "marketing/campaigns/summer-2024",
  "updatedAt": "2026-03-18T16:05:00Z",
  "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
}
```

### Parameters

`pageSize` integer (int64) 

query

Required

The maximum number of directories to return

`pageToken` string 

query

The token for retrieving the next page of results If not provided, the first page of results will be returned

`parentDirectoryId` string 

query

Filter directories by parent. When empty, returns root-level directories.

`search` string 

query

Search query to filter directories by name

Search query to filter directories by name

`includeRoot` boolean 

query

When listing with parentDirectoryId, also include root-level directories if true

When listing with parentDirectoryId, also include root-level directories.

`recursive` boolean 

query

When true, returns all directories recursively regardless of parent filter Useful for getting a complete flat list of all directories in the workspace (e.g., for directory pickers) When false (default), returns only immediate children based on parentDirectoryId

Return all directories recursively. When true with empty parentDirectoryId, returns all directories in workspace. When true with parentDirectoryId set, returns all descendants of that directory.

`cursor` string 

query

Opaque cursor from the previous page's nextPageToken. Same as pageToken; when both are sent, pageToken wins.

### Response

200

`directories` array of object

The list of directories matching the filter criteria

Fields: [The directory object](#directories-object).

`nextPageToken` string

Token for retrieving the next page of results.

Cursor to continue listing directories

`totalCount` integer (int64)

How many records exist in total, so a client can tell a complete answer from a page of one. A local-first client reads absence from this list as deletion, and may only do so when the count it was given matches what it received: without that, one page would look like the whole model and everything beyond it would be removed locally.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/directories?pageSize={pageSize}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "directories": [
    {
      "createdAt": "2026-03-14T09:30:00Z",
      "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
      "name": "Table cards",
      "parentDirectoryId": "4e6a8c0d-2f1b-4d3e-9a5c-7b9d1f3e5a28",
      "path": "marketing/campaigns/summer-2024",
      "updatedAt": "2026-03-18T16:05:00Z",
      "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
    }
  ],
  "nextPageToken": "eyJkaXJlY3RvcnlJZCI6IjEwIn0=",
  "totalCount": 3
}
```

### Parameters

`id` string 

path

Required

The ID of the directory to retrieve (UUID)

### Response

200

`directory` object

A folder of links and other directories within a workspace.

Fields: [The directory object](#directories-object).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X GET "https://api.linkbreakers.com/v1/directories/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

Response 200

```json
{
  "directory": {
    "createdAt": "2026-03-14T09:30:00Z",
    "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
    "name": "Table cards",
    "parentDirectoryId": "4e6a8c0d-2f1b-4d3e-9a5c-7b9d1f3e5a28",
    "path": "marketing/campaigns/summer-2024",
    "updatedAt": "2026-03-18T16:05:00Z",
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  }
}
```

### Parameters

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`name` string 

Required

The name of the directory. This field is required.

`parentDirectoryId` string

The ID of the parent directory (UUID) If not provided, the directory will be created at the root level.

### Response

200

`directory` object

A folder of links and other directories within a workspace.

Fields: [The directory object](#directories-object).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X POST "https://api.linkbreakers.com/v1/directories" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "My Directory",
  "parentDirectoryId": "4e6a8c0d-2f1b-4d3e-9a5c-7b9d1f3e5a28"
}'
```

Response 200

```json
{
  "directory": {
    "createdAt": "2026-03-14T09:30:00Z",
    "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
    "name": "Table cards",
    "parentDirectoryId": "4e6a8c0d-2f1b-4d3e-9a5c-7b9d1f3e5a28",
    "path": "marketing/campaigns/summer-2024",
    "updatedAt": "2026-03-18T16:05:00Z",
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  }
}
```

### Parameters

`id` string 

path

Required

The ID of the directory to update (UUID)

`Idempotency-Key` string 

header

A unique value per request, such as a UUID, that makes retrying it safe: a retry with the same key and body returns the first response instead of acting twice.

### Request body

`name` string

The new name of the directory

`parentDirectoryId` string

The ID of the parent directory to move this directory under (UUID)

`parentDirectoryIdDelete` boolean

Move the directory to root level by removing its parent If true, the parentDirectoryId will be set to null

### Response

200

`directory` object

A folder of links and other directories within a workspace.

Fields: [The directory object](#directories-object).

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X PATCH "https://api.linkbreakers.com/v1/directories/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "My Updated Directory",
  "parentDirectoryId": "4e6a8c0d-2f1b-4d3e-9a5c-7b9d1f3e5a28",
  "parentDirectoryIdDelete": false
}'
```

Response 200

```json
{
  "directory": {
    "createdAt": "2026-03-14T09:30:00Z",
    "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
    "name": "Table cards",
    "parentDirectoryId": "4e6a8c0d-2f1b-4d3e-9a5c-7b9d1f3e5a28",
    "path": "marketing/campaigns/summer-2024",
    "updatedAt": "2026-03-18T16:05:00Z",
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  }
}
```

### Parameters

`id` string 

path

Required

The ID of the directory to delete. The directory must be empty before deletion; if it still contains links or child directories, the request fails.

### Response

200

An empty JSON object.

Errors answer 4xx or 5xx with the [error object](https://linkbreakers.com/help/api#errors), and `429` past the [rate limit](https://linkbreakers.com/help/api#rate-limits).

Request

```bash
curl -X DELETE "https://api.linkbreakers.com/v1/directories/{id}" \
  -H "Authorization: Bearer $LINKBREAKERS_TOKEN"
```

---

Source: https://linkbreakers.com/help/api/directories
