v24

latestOpenAPI 3.1.0MITraw.githubusercontent.com2026-08-012843108.3 KB
Folders

Get User Folders

Get all folders for the authenticated user.

This endpoint is strictly read-only and returns an empty list if the user has no folders. Unlike the internal /v1/folders endpoint, it does NOT call initialize_system_folders, because doing so under a conversations:read scope would silently write to Firestore (violating the read-only contract) and opens a TOCTOU window where concurrent first requests can race past the outer empty-check and create duplicate system folders.

System folders (Work, Personal, Social) are still initialized lazily through other paths:

  • The mobile app calls the internal GET /v1/folders whenever the conversations screen is rendered (app/lib/pages/conversations/conversations_page.dart), which triggers initialize_system_folders on first access.
  • The conversation post-processing pipeline calls initialize_system_folders whenever a new conversation is created (backend/utils/conversations/process_conversation.py).

In practice, any user who can issue a Developer API key has already gone through one of those paths, so the empty-list case here only affects users who have never opened the conversations tab nor created a single conversation.

get/v1/dev/user/folders

Response

Successful Response

colorstring required
conversation_countinteger
created_atstring date-time required
descriptionstring nullable
iconstring required
idstring required
is_defaultboolean
is_systemboolean
namestring required
orderinteger
updated_atstring date-time required