List a folder

listChildren

GET /api/v1/shares/{share_id}/children

Scope: foldr.readRate cost: 1

The files and folders in a folder, folders first, then by name

Pages hold a snapshot of the folder taken on the first page and kept for a minute while it is paged through: a folder that changes in the meantime shows the snapshot; a cursor whose snapshot has gone answers 410, so start again from the first page. A folder of more than 25,000 entries is paged as the first 25,000 the storage lists, and every page of it says truncated: true.

Request

curl "$FOLDR/api/v1/shares/$SHARE_ID/children" \
  -H "Authorization: Bearer $TOKEN"

$FOLDR is your site’s address (for example https://files.example.com) and $TOKEN is an access token. See Getting access.

Parameters

Name	In	Type	Required	Description
share_id	path	string	Yes	The share’s id.
path	query	string	No	Path of the folder; ”/”, empty or absent for the top of the share (a path of only spaces is refused).
cursor	query	string	No	From a previous page’s next_cursor.
limit	query	integer	No	Items per page, from 1: default 100; more than 200 is read as 200. 0 is refused.

Responses

Status	Meaning	Body
200	One page of Items.	application/json: ItemPage

200 response

ItemPage:

Field	Type	Description
items	array of Item	Required. This page’s entries.
next_cursor	string or null	Required. The cursor for the next page, or null when this is the last.
truncated	boolean	Required. True when the collection holds more than one listing can read (a folder of more than 25,000 entries): the pages give the first 25,000 the storage lists, and every page of it says true, so a null next_cursor is not the whole folder. False otherwise.

Example:

{
  "items": [
    {
      "share_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
      "path": "string",
      "name": "string",
      "kind": "file",
      "size": 1,
      "modified": "2026-11-04T09:30:00Z",
      "mime_type": "string",
      "export": {},
      "etag": "string",
      "read_only": false,
      "checked_out": {}
    }
  ],
  "next_cursor": "string",
  "truncated": false
}

Errors

Every error is an application/problem+json document (ProblemDetails); branch on its type or code. See Errors.

Status	Problem types	When
400	invalid-cursor invalid-path invalid-request	One of: Invalid cursor (invalid-cursor); Invalid path (invalid-path); Invalid request (invalid-request).
401	invalid-token	Invalid token (invalid-token).
403	insufficient-scope	Insufficient scope (insufficient-scope).
404	not-found	Not found (not-found).
409	ambiguous-path not-a-folder storage-account-not-connected	One of: Ambiguous path (ambiguous-path); Not a folder (not-a-folder); Storage account not connected (storage-account-not-connected).
410	cursor-expired	Cursor expired (cursor-expired).
429	rate-limited	Too many requests (rate-limited).
500	internal-error	Internal error (internal-error).
503	share-unavailable share-unreachable	One of: Share unavailable (share-unavailable); Share unreachable (share-unreachable).