v1

latestOpenAPI 3.1.02026-07-226875162.5 KB

Folder

Create Folder

Create a folder in a workspace.

Requires a user API key — you must be a writable member of the workspace. A team-only API key returns 401.

To nest the folder, set parentId (folders can be nested up to 5 levels below the root level). sharingType defaults to ALL_MEMBER_VIEWER when omitted.

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

Path parameters

workspaceGuidstring required

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

Request body

titlestring required

Folder title. Must not be blank.

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

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

Parent folder ID for a nested folder. Omit or set to null to create at the root level. Folders can be nested up to 5 levels below the root level.

descriptionstring nullable

Folder description. Defaults to an empty string.

colorstring nullable

Folder color in hex format (#RRGGBB). Defaults to #737373.

Example request

{
  "title": "Q1 2025 Meetings",
  "sharingType": "PRIVATE",
  "parentId": "12300",
  "description": "Daily engineering standup notes",
  "color": "#27AE60"
}

Response

Folder created

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"
}