---
title: "Get User Folders"
method: GET
path: "/v1/dev/user/folders"
tags: ["Folders"]
---

# Get User Folders

`GET /v1/dev/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.

## Response `200`

Successful Response

- DeveloperFolder[]
  - `color` string, required
  - `conversation_count` integer
  - `created_at` string, date-time, required
  - `description` string, nullable
  - `icon` string, required
  - `id` string, required
  - `is_default` boolean
  - `is_system` boolean
  - `name` string, required
  - `order` integer
  - `updated_at` string, date-time, required

## Other responses

- `401` — Missing or invalid authentication credentials.
- `403` — Authenticated, but the token does not grant the required scope.

## Changes

> 28 revisions in range; 6 could not be searched.

- **2026-06-29** `a638dcb24d6f` — 6 breaking, 1 warning, 11 info
  - response property `detail` list-of-types was widened by adding types `array and object` to media type `application/json` of response `401`
  - response property `detail` list-of-types was widened by adding types `array and object` to media type `application/json` of response `403`
  - response property `items/description` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - the `items/description` response property's maxLength was unset from `500` for the response status `200`
  - …14 more
- **2026-04-30** `1b86160bd22e` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/basedhardware/apis/omi-developer-api/changes/v1/dev/user/folders/get.md)

---

[API](https://skmtc.dev/basedhardware/apis/omi-developer-api.md) · [All operations](https://skmtc.dev/basedhardware/apis/omi-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/basedhardware/omi-developer-api/revisions/3add0ce9bc4f/schema)