Folder API

FolderClient manages project-scoped folders. Folders are always scoped to a project.

Access

const folder = client.folders('project-id');

note

Unlike other resource clients, FolderClient requires a projectId at construction time because folder endpoints are project-scoped.

Methods

Common Tasks

• list folders inside one project
• create folder structures for workflow organization
• rename or move folders
• delete a folder while transferring its contents elsewhere

list(params?)

List folders in the project.

const { data } = await client.folders('proj-123').list({
  limit: 10,
  filter: 'name',
  sortBy: 'name:asc',
});

get(folderId)

Get a folder by ID.

const folder = await client.folders('proj-123').get('folder-456');

create(data)

Create a new folder.

const folder = await client.folders('proj-123').create({
  name: 'Production Workflows',
});

update(folderId, data)

Update a folder.

const updated = await client.folders('proj-123').update('folder-456', {
  name: 'Prod Workflows',
});

delete(folderId, transferToFolderId?)

Delete a folder, optionally transferring its contents to another folder.

await client.folders('proj-123').delete('folder-456');
// or transfer contents first
await client.folders('proj-123').delete('folder-456', 'other-folder-789');

Typical Flow

const folder = client.folders('proj-123');

const created = await folder.create({ name: 'Ops Workflows' });
await folder.update(created.id, { name: 'Operations Workflows' });

FolderResource

Use getResource(), listResources(), or createResource() to get a bound FolderResource instance.

const resource = await client.folders('proj-123').getResource('folder-456');
const created = await client.folders('proj-123').createResource({ name: 'Archives' });

note

listResources() does not support cursor-based pagination. It always returns nextCursor: undefined. Use list() directly if you need to page through folders.

Properties

Property	Type	Description
id	string	Folder ID
name	string	Folder name
parentFolderId	string | undefined	Parent folder ID (if nested)

Methods

Method	Returns	Description
update(data)	this	Update the folder — replaces snapshot with the API response
patch(data)	this	Convenience update — merges partial fields into the current folder snapshot before updating
delete(transferToFolderId?)	void	Delete the folder, optionally moving contents to another folder