Search Folders

post

https://api.lucid.co/v1/folders/search

Retrieves information about folders the authenticated user has at least read-only access to. Admin requests using the Lucid-Request-As: admin header return all account folders; this capability is exclusive to Enterprise Shield accounts. Results are sorted by creation date and paginated. Rate limited to 300 requests per 5 seconds per account.

Retrieves information about folders the authenticated user has at least read only access to. Additional filtering parameters may be added.

The ability to use this API to search for all account folders is exclusive to Enterprise Shield accounts.

Only the account owner or a document admin can grant access to the admin version of this API.
Admins can search all account folders belonging to the requested user's account.

📘
The list of folders returned depends on whether the request was made using user or admin permissions, sorted by created date.

User: folders the requesting user has access to and matching search parameters

Must request with a user grant/scope and either omit the header Lucid-Request-As or contain the value user.

Admin: folders belonging to the account and matching search parameters

Must request with an admin grant/scope and contain the header Lucid-Request-As with value admin.

📘
This endpoint is paginated. For more information, see Pagination .

📘
This endpoint has a per account rate limit of 300 requests per 5 seconds.

Valid Authentication Methods

API Key Grants:

FolderReadonly
FolderAdmin

OAuth 2.0 User Token Scopes:

folder:readonly
folder:admin.readonly
lucidchart.document.app.folder
lucidspark.document.app.folder
lucidscale.document.app.folder

Body Params

type

string

enum

Note: This endpoint only accepts the folder type

Allowed:

userIds

array of numbers

If provided, limit the search to folders that at least one specified user can access.
Without a list, the system searches the entire account (admin-level) or only folders the authenticated user can access (user-level).

userIds

ownedByUsers

boolean

When true, search results will only include folders owned by users specified by userIds. Ignored if no userIds are provided.

keywords

string

Keywords to search against folder content and titles. This field is truncated to 400 characters. When provided, results will be sorted by relevance to keyword search.

appFolder

boolean

When set to true, restricts search results to folders within the OAuth2 client's app project folder. Required when using a document.app.folder scope without a folder:readonly scope.

Headers

Lucid-Request-As

string

required

If the requesting user is an account owner or folder admin with the required permissions and they make the request
with the value of “admin” as this header and include an admin scope, the request will be made using their admin
permissions.
Account owners and document admins can access the admin version of folder search.

Responses

400

Bad Request.

The request does not contain a body.
When using a document.app.folder scope, appFolder must be set to true.

403

Forbidden.

User requests with admin scope and without Lucid-Request-As=admin header.
User requests without an admin scope and includes Lucid-Request-As=admin header.
Account does not have access to the API.
When using a document.app.folder scope without setting appFolder to true.

429

Too Many Requests if the account makes more than 300 requests in 5 seconds.

The list of folders returned depends on whether the request was made using user or admin permissions, sorted by created date.

This endpoint is paginated. For more information, see Pagination .

This endpoint has a per account rate limit of 300 requests per 5 seconds.

Valid Authentication Methods

API Key Grants:

OAuth 2.0 User Token Scopes:

200OK with an array of Folder Resource objects containing information about folders the authenticated user has access to.