> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omi.me/llms.txt
> Use this file to discover all available pages before exploring further.

# List 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.



## OpenAPI

````yaml /api-reference/openapi.json get /v1/dev/user/folders
openapi: 3.1.0
info:
  title: Omi Developer API
  description: >-
    Programmatic access to your Omi data — memories, conversations, action
    items, and API keys. Build custom integrations, analytics dashboards, and
    automation workflows.
  version: 1.0.0
  contact:
    name: Omi
    url: https://omi.me
  license:
    name: MIT
    url: https://github.com/BasedHardware/omi/blob/main/LICENSE
servers:
  - url: https://api.omi.me
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Memories
    description: Read and write user memories — timeless facts, preferences, and insights.
  - name: Conversations
    description: Create and retrieve conversation transcripts with AI-generated summaries.
  - name: Folders
    description: Retrieve user-defined folders for organizing conversations.
  - name: Action Items
    description: Manage tasks and to-dos extracted from conversations or created manually.
  - name: API Keys
    description: Create, list, and revoke developer API keys.
paths:
  /v1/dev/user/folders:
    get:
      tags:
        - Folders
      summary: List folders
      description: >-
        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.
      operationId: listFolders
      parameters: []
      responses:
        '200':
          description: List of folders.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Folder'
              example:
                - id: folder_uuid_work
                  name: Work
                  description: >-
                    Work, business, professional, and career-related
                    conversations
                  color: '#3B82F6'
                  icon: 💼
                  created_at: '2025-01-15T10:00:00Z'
                  updated_at: '2025-01-20T13:50:00Z'
                  order: 0
                  is_default: false
                  is_system: true
                  category_mapping: work
                  conversation_count: 12
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: 'Insufficient permissions. Required scope: `conversations:read`.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                detail: 'Insufficient permissions. Required scope: conversations:read'
components:
  schemas:
    Folder:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier.
        name:
          type: string
          minLength: 1
          maxLength: 100
          description: Display name of the folder.
        description:
          type:
            - string
            - 'null'
          maxLength: 500
          description: Natural language description of what belongs in this folder.
        color:
          type: string
          default: '#6B7280'
          description: Hex color code for the folder.
        icon:
          type: string
          default: folder
          description: Emoji or icon identifier for the folder.
        created_at:
          type: string
          format: date-time
          description: When the folder was created.
        updated_at:
          type: string
          format: date-time
          description: When the folder was last updated.
        order:
          type: integer
          default: 0
          description: Display order index (lower = earlier).
        is_default:
          type: boolean
          default: false
          description: Whether this is the default folder for unassigned conversations.
        is_system:
          type: boolean
          default: false
          description: True for category-based system folders (Work, Personal, Social).
        category_mapping:
          type:
            - string
            - 'null'
          description: >-
            Maps to a CategoryEnum value for backwards compatibility with
            category-based filtering.
        conversation_count:
          type: integer
          default: 0
          description: Number of non-discarded conversations in this folder.
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          description: Error description.
  responses:
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            detail: Invalid API key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Developer API key. Get one from **Settings → Developer → Create Key** in
        the Omi app. Keys are prefixed with `omi_dev_`.

````