Folders

Update folder

Rename, recolour, pin, reorder, or change the session sort of a folder. At least one of name (trimmed, 1–100 characters), color (hex like #4D5EF6, or null to clear), pinned (boolean), sort_order (newest | oldest | title), or order (integer >= 0, manual position) is required; omitted fields are unchanged. Bumps updated_at. Membership is managed separately via the session-folder endpoints. Requires the folders:write scope.

patch/v1/folders/{id}

Request

  • Base URL: https://api.wave.co
  • URL: https://api.wave.co/v1/folders/{id}
  • Auth: HTTP bearer

Path parameters

idstring required

Folder ID

Example:fld_01HX4R7MT8PQZ6VCN9ABYF2KJM

Request body

OR
OR
OR
OR

Response

Updated folder

idstring required
namestring required
colorstring nullable required
session_countnumber required
created_atstring

ISO 8601. Absent on folders created before timestamps were introduced.

updated_atstring

ISO 8601. Bumped on rename, recolour, pin/reorder/sort changes, and membership changes. Absent on folders never mutated since timestamps were introduced.

pinnedboolean

Pinned folders sort first everywhere. Absent means not pinned.

sort_order'newest' | 'oldest' | 'title'

Remembered sort for the sessions inside a folder: newest (session timestamp descending; the default when absent), oldest, or title.

orderinteger

Manual position (integer from 0 to 2^53 - 1). Folders with order sort ascending before folders without it. Absent means no manual position.

last_opened_atstring

ISO 8601. When the folder's contents were last viewed in a Wave client. Absent if never recorded.

Example response

{
  "id": "fld_01HX4R7MT8PQZ6VCN9ABYF2KJM",
  "name": "work",
  "color": "#6D28D9",
  "session_count": 82,
  "created_at": "2026-09-01T14:02:11.000Z",
  "updated_at": "2026-09-05T09:41:37.000Z",
  "pinned": true,
  "sort_order": "newest",
  "order": 0,
  "last_opened_at": "2026-09-06T08:15:02.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.