Folders

List folders

GET/folders
documents:readlist_foldersRead-only

Lists the folders the token can see, newest first, and returns one page. A token sees folders whose read or write list holds its user, folders whose write flags its user satisfies (internal staff, entrepreneur, file upload, deal manager), and every folder in the tree of a deal it can see. Hidden folders are included; send filter[hidden]=false to leave them out. This deliberately differs from the old folder routes, which answered 404 for hidden folders. Deleted folders are never listed. Use GET /folders/{id} for one folder. It changes nothing.

Query parameters

  • limitinteger#

    Page size (1–100). Defaults to 25; values are clamped to the range.

    Default: 25
  • cursorstring#

    Opaque pagination cursor taken from a prior response's meta.next_cursor.

  • fieldsstring#

    Comma-separated top-level fields to return. id is always returned.

  • includestring#

    Set to permissions to embed who may read and write each folder.

  • totalsboolean#

    Send true to add the number of folders the token can see, across every match and not just this page, to meta.totals.

  • sortstring#

    Comma-separated fields to sort by: created_at or name. Prefix a field with - for descending. Defaults to -created_at. The folder id is always the final tiebreak.

  • filter[q]string#

    Folders whose name contains this text, ignoring case.

  • filter[parent_id]string (uuid)#

    Direct children of this folder. Send filter[parent_id][null]=true for root folders. Takes [in] and [not_in] with a comma-separated list.

  • filter[deal_id]string (uuid)#

    Folders in this deal's folder tree, the deal's root folder included. Takes [in] and [not_in] with a comma-separated list.

  • filter[workflow_step_id]string (uuid)#

    Folders linked to this transaction workflow step. Takes [in] and [not_in] with a comma-separated list.

  • filter[namespace]string#

    Folders the platform uses for this purpose. Takes [in] and [not_in] with a comma-separated list. Each value is described under x-enum-descriptions.

    One of: attachment.sig.root, attachment.sig.entity, attachment.user.custom, attachment.sig.entity.counter, attachment.sig.entity.counter.internal, attachment.user.other, attachment.user.other.default, deal.core.assets, deal.core.deal_information, deal.core.root, deal.core.text_editor_uploads, deal.tm.committed, deal.tm.confirmed, deal.tm.custom, deal.tm.preinvestment, portfolio.root, portfolio.user.documents, portfolio.asset.public, team.core.root, team.core.termsandconditions
  • filter[type_id]string (uuid)#

    Folders of this type. Send filter[type_id][null]=true for folders with none. Takes [in] and [not_in] with a comma-separated list. Use GET /folder-types for the ids.

  • filter[hidden]boolean#

    Only hidden folders when true, only visible folders when false.

Responses

200

The folders.

FolderListWithTotals
{
  "data": [
    {}
  ],
  "meta": {
    "totals": [
      {}
    ]
  }
}
401

Authentication failed. error.code is one of invalid_token, expired, revoked.

Error
403

Authorization failed. error.code is one of org_disabled, ip_blocked, missing_scope, scope_disabled, user_disabled.

Error
422

The request can't be processed (HTTP 422): validation_failed with one ErrorDetail per problem, or a code documented on the operation.

Error
429

Rate limit exceeded (error.code = rate_limited).

Error

Examples

curl https://your-org-domain/kong/core/api/v2/folders\
  -H "Authorization: Bearer $HELM_API_KEY"\
  -H "Content-Type: application/json"