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

# List folders

`GET /v1/dev/user/folders`

Retrieve all folders for the authenticated user. This endpoint is strictly read-only and returns an empty list if the user has no folders yet. System folders (Work, Personal, Social) are initialized lazily through other paths (the mobile app opening the conversations screen, or the conversation post-processing pipeline), not by this endpoint.

## Response `200`

List of folders.

- Folder[]
  - `id` string — Unique identifier.
  - `name` string — Display name of the folder.
  - `description` string, nullable — Natural language description of what belongs in this folder.
  - `color` string — Hex color code for the folder.
  - `icon` string — Emoji or icon identifier for the folder.
  - `created_at` string, date-time — When the folder was created.
  - `updated_at` string, date-time — When the folder was last updated.
  - `order` integer — Display order index (lower = earlier).
  - `is_default` boolean — Whether this is the default folder for unassigned conversations.
  - `is_system` boolean — True for category-based system folders (Work, Personal, Social).
  - `category_mapping` string, nullable — Maps to a CategoryEnum value for backwards compatibility with category-based filtering.
  - `conversation_count` integer — Number of non-discarded conversations in this folder.

## Other responses

- `401` — Invalid or missing API key.
- `403` — Insufficient permissions. Required scope: `conversations:read`.

## Changes

- **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/e3d644927120/schema)