Skip to main content

List directories

GET /projects/:projectid/library/dirs

Returns the immediate child directories of a Library directory. Use their IDs as upload destinations.

Authentication and request​

Use a project key with library.read in Authorization, without Bearer. Replace :projectid with the key's project ID.

Omit the optional path query parameter to list the root. To browse deeper, supply a case-sensitive relative path such as Reports/Monthly, with no leading or trailing slash.

This example lists the root using the Quickstart variables:

curl --include --request GET \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/library/dirs"

To list children of Reports, use --get with --data-urlencode "path=Reports". There is no request body or pagination.

Response​

200 OK returns a dirs array:

{
"dirs": [
{
"id": "example-directory-id",
"name": "Reports",
"parent": "root",
"childrenCount": 2,
"docCount": 3
}
]
}
FieldMeaning
idDirectory ID. Pass this as dir when creating a file.
nameDisplay name used to form directory paths.
parentParent directory ID, or null if unavailable.
childrenCountNumber of immediate child-directory references.
docCountNumber of immediate file references.

Counts are not recursive totals or a guarantee that all referenced files have completed uploading. No child directories means {"dirs":[]}; files in the directory are listed separately by List files.

Build nested paths from the returned names, but use directory IDs for upload destinations. The public Library API does not create folders; create them in the app first.

Errors​

  • 401: missing or invalid project credential.
  • 403: missing library.read.
  • 404: no directory matches the supplied path.
  • 429: request-rate limit reached.
  • 500: the listing could not be retrieved.

See Errors, limits and retries.