Folders

Create folder

Create a new folder. Name collisions (case-insensitive) return the existing folder — the endpoint is safe to retry. name is trimmed and must be 1–100 characters; color is a hex string like #6D28D9 or null. The folder is stamped with created_at / updated_at. Requires the folders:write scope.

post/v1/folders

Request

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

Request body

namestring required

Folder name. Trimmed; 1–100 characters, not blank.

colorstring nullable

Hex colour like #6D28D9, or null for no colour.

Example request

{
  "name": "client-calls",
  "color": "#6D28D9"
}

Response

Folder created (or returned if it already existed)

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.