Logo of linkbreakers
← Back to API Reference overview

Directories

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

Shortcut: ⌘K

#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)

GET/v1/directoriesRequires auth

#List directories

List directories in the workspace with optional filtering by parent directory, search, and pagination.

#Parameters

query parameters

pageSize

integer (int64)Requiredquery

The maximum number of directories to return

pageToken

stringquery

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

parentDirectoryId

stringquery

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

search

stringquery

Search query to filter directories by name Search query to filter directories by name

includeRoot

booleanquery

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

booleanquery

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.

#Response

200

Everything worked as expected.

directories

array<object>

The list of directories matching the filter criteria

nextPageToken

string

Cursor to continue listing directories

#Error response

400-599

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

error

objectRequired

Wrapped error response.

GET/v1/directories/{id}Requires auth

#Get a directory

Retrieve a directory by its unique identifier.

#Parameters

path parameters

id

stringRequiredpath

The ID of the directory to retrieve (UUID)

#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.

#Error response

400-599

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

error

objectRequired

Wrapped error response.

POST/v1/directoriesRequires auth

#Create a directory

Create a new directory in the workspace. Optionally nest it under an existing directory.

#Parameters

This endpoint does not accept any parameters.

#Request body

name

stringRequired

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

Everything worked as expected.

directory

object

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

#Error response

400-599

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

error

objectRequired

Wrapped error response.

PATCH/v1/directories/{id}Requires auth

#Update a directory

Update a directory's name or move it under a different parent directory.

#Parameters

path parameters

id

stringRequiredpath

The ID of the directory to update (UUID)

#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

#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.

#Error response

400-599

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

error

objectRequired

Wrapped error response.

DELETE/v1/directories/{id}Requires auth

#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.

#Parameters

path parameters

id

stringRequiredpath

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

Everything worked as expected.

No structured schema available for this section.

#Error response

400-599

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

error

objectRequired

Wrapped error response.