---
title: "Directories API Reference"
description: "Endpoints for managing directories in Linkbreakers. Directories let you organize links and other directories into a hierarchical folder structure."
canonical: "https://linkbreakers.com/help/api/directories"
---

# Directories

Endpoints for managing directories in Linkbreakers. Directories let you organize links and other directories into a hierarchical folder structure.

## Directories

## [#](#directories-object)The Directory object

An organizational bucket that groups links and other directories into a hierarchical folder structure within a workspace.

createdAt

string (date-time)

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

Full hierarchical path separated by slashes, computed server-side

updatedAt

string (date-time)

When the directory was last updated

workspaceId

string

The workspace ID the directory belongs to (UUID)

[Learn moreLearn more about directories in Linkbreakers.](https://linkbreakers.com/help/article/what-is-a-directory-in-linkbreakers)

Example object

```json
{
  "createdAt": "2026-10-13T00:24:49.073Z",
  "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
  "name": "string",
  "parentDirectoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "path": "marketing/campaigns/summer-2024",
  "updatedAt": "2026-10-13T00:24:49.073Z",
  "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
}
```

GET

`/v1/directories`

Requires auth

## [#](#list-directories)List directories

List directories in the workspace with optional filtering by parent directory, search, and pagination. Requires the \`links:read\` scope.

### [#](#list-directories-parameters)Parameters

#### query parameters

pageSize

integer (int64)

Required

query

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 parent\_directory\_id, also include root-level directories if true When listing with parent\_directory\_id, 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 parent\_directory\_id Return all directories recursively. When true with empty parent\_directory\_id, returns all directories in workspace. When true with parent\_directory\_id 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.

### [#](#list-directories-response)Response

200

Everything worked as expected.

directories

array<object>

The list of directories matching the filter criteria

nextPageToken

string

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.

### [#](#list-directories-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X GET "https://api.linkbreakers.com/v1/directories?pageSize={pageSize}&pageToken={pageToken}&parentDirectoryId={parentDirectoryId}&search={search}&includeRoot={includeRoot}&recursive={recursive}&cursor={cursor}" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

Typical response

```json
{
  "directories": [
    {
      "createdAt": "2026-10-13T00:24:49.073Z",
      "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
      "name": "string",
      "parentDirectoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "path": "marketing/campaigns/summer-2024",
      "updatedAt": "2026-10-13T00:24:49.073Z",
      "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
    }
  ],
  "nextPageToken": "eyJkaXJlY3RvcnlJZCI6IjEwIn0=",
  "totalCount": 0
}
```

Base URL: `https://api.linkbreakers.com`

GET

`/v1/directories/{id}`

Requires auth

## [#](#get-a-directory)Get a directory

Retrieve a directory by its unique identifier. Requires the \`links:read\` scope.

### [#](#get-a-directory-parameters)Parameters

#### path parameters

id

string

Required

path

The ID of the directory to retrieve (UUID)

### [#](#get-a-directory-response)Response

200

Everything worked as expected.

directory

object

An organizational bucket that groups links and other directories into a hierarchical folder structure within a workspace.

### [#](#get-a-directory-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

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

Typical response

```json
{
  "directory": {
    "createdAt": "2026-10-13T00:24:49.073Z",
    "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
    "name": "string",
    "parentDirectoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "path": "marketing/campaigns/summer-2024",
    "updatedAt": "2026-10-13T00:24:49.073Z",
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  }
}
```

Base URL: `https://api.linkbreakers.com`

POST

`/v1/directories`

Requires auth

## [#](#create-a-directory)Create a directory

Create a new directory in the workspace. Optionally nest it under an existing directory. Requires the \`links:write\` scope.

### [#](#create-a-directory-parameters)Parameters

#### header parameters

Idempotency-Key

string

header

Makes retrying this request safe. See components.parameters.IdempotencyKey.

### [#](#create-a-directory-request)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.

### [#](#create-a-directory-response)Response

200

Everything worked as expected.

directory

object

An organizational bucket that groups links and other directories into a hierarchical folder structure within a workspace.

### [#](#create-a-directory-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X POST "https://api.linkbreakers.com/v1/directories" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  --data '{"name":"My Directory","parentDirectoryId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'
```

Sample payload (application/json)

```json
{
  "name": "My Directory",
  "parentDirectoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
```

Typical response

```json
{
  "directory": {
    "createdAt": "2026-10-13T00:24:49.073Z",
    "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
    "name": "string",
    "parentDirectoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "path": "marketing/campaigns/summer-2024",
    "updatedAt": "2026-10-13T00:24:49.073Z",
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  }
}
```

Base URL: `https://api.linkbreakers.com`

PATCH

`/v1/directories/{id}`

Requires auth

## [#](#update-a-directory)Update a directory

Update a directory's name or move it under a different parent directory. Requires the \`links:write\` scope.

### [#](#update-a-directory-parameters)Parameters

#### path parameters

id

string

Required

path

The ID of the directory to update (UUID)

#### header parameters

Idempotency-Key

string

header

Makes retrying this request safe. See components.parameters.IdempotencyKey.

### [#](#update-a-directory-request)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 parent\_directory\_id will be set to null

### [#](#update-a-directory-response)Response

200

Everything worked as expected.

directory

object

An organizational bucket that groups links and other directories into a hierarchical folder structure within a workspace.

### [#](#update-a-directory-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

```bash
curl -X PATCH "https://api.linkbreakers.com/v1/directories/{id}" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  --data '{"name":"My Updated Directory","parentDirectoryId":"a1b2c3d4-e5f6-7890-abcd-ef1234567890","parentDirectoryIdDelete":false}'
```

Sample payload (application/json)

```json
{
  "name": "My Updated Directory",
  "parentDirectoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "parentDirectoryIdDelete": false
}
```

Typical response

```json
{
  "directory": {
    "createdAt": "2026-10-13T00:24:49.073Z",
    "id": "d87a9b30-5c8b-4d4e-9fd3-5f5f5f5f5f5f",
    "name": "string",
    "parentDirectoryId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "path": "marketing/campaigns/summer-2024",
    "updatedAt": "2026-10-13T00:24:49.073Z",
    "workspaceId": "c0d3cafe-5b1e-4d42-a6fd-0c5f5c3962d0"
  }
}
```

Base URL: `https://api.linkbreakers.com`

DELETE

`/v1/directories/{id}`

Requires auth

## [#](#delete-a-directory)Delete a directory

Remove a directory from the workspace. This operation cannot be undone. A directory cannot be deleted while it still contains links or child directories; move or remove them first. Requires the \`links:write\` scope.

### [#](#delete-a-directory-parameters)Parameters

#### path parameters

id

string

Required

path

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.

### [#](#delete-a-directory-response)Response

200

Everything worked as expected.

No structured schema available for this section.

### [#](#delete-a-directory-error)Error response

400-599

All endpoints may return an unexpected error payload when a request cannot be processed.

error

object

Required

Wrapped error response.

Example request (cURL)

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

Typical response

```json
{}
```

Base URL: `https://api.linkbreakers.com`

Cookies

We use cookies to measure our ads with Meta and Google. Our own analytics are cookie-free and run either way. [Privacy statement](https://linkbreakers.com/privacy#cookies)

---

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