v1

latestOpenAPI 3.1.02026-07-226875162.5 KB

Folder

List Folders

List the folders you can access in a workspace, as a flat array.

Requires a user API key — folder access is evaluated per user via workspace membership. A team-only API key returns 401.

Create folders with POST on this same path. Read and manage individual folders with the endpoints under /v1/external/folders/{folderId}.

get/v1/external/workspaces/{workspaceGuid}/folders

Path parameters

workspaceGuidstring required

Workspace GUID. Obtain it from GET /v1/external/workspaces.

Response

Folders you can access in the workspace

idstring required

Unique identifier for the folder

workspaceGuidstring required

GUID of the workspace the folder belongs to

titlestring required

Folder title (max 50 characters)

descriptionstring required

Folder description. Empty string when unset.

sharingType'PRIVATE' | 'ALL_MEMBER_VIEWER' | 'ALL_MEMBER_EDITOR' | 'LIMITED' required

Who can access a folder and the notes inside it.

Type	View	Edit
PRIVATE	Only you	Only you
ALL_MEMBER_VIEWER	All workspace members	No member-wide edit access
ALL_MEMBER_EDITOR	All workspace members	All workspace members
LIMITED	Invited members only	Invited members only (per-member role)

PRIVATE: Personal folder. Not shared with the workspace.
ALL_MEMBER_VIEWER: Every workspace member can view; no member-wide edit access is granted.
ALL_MEMBER_EDITOR: Every workspace member can view and edit.
LIMITED: Only explicitly invited members can access, each with an individual role (VIEWER or EDITOR).

parentIdstring nullable required

Parent folder ID. null for root-level folders. In the List Folders response, parentId is also null when the parent folder is not accessible to you.

colorstring required

Folder color in hex format (#RRGGBB)

isTeamFolderboolean required

true when the folder is shared with the workspace (any sharingType except PRIVATE); false for PRIVATE folders. Retained for backward compatibility — use sharingType for the precise access level.

createdAtstring date-time required

ISO-8601 creation timestamp (UTC)

updatedAtstring date-time required

ISO-8601 last-update timestamp (UTC)

Example response

[
  {
    "id": "12345",
    "workspaceGuid": "ws_a1b2c3d4",
    "title": "Weekly Team Meetings",
    "description": "Notes from our weekly sync",
    "sharingType": "PRIVATE",
    "parentId": "12300",
    "color": "#4A90D9",
    "isTeamFolder": true,
    "createdAt": "2025-01-15T10:30:00Z",
    "updatedAt": "2025-01-18T14:20:00Z"
  }
]