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

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



## OpenAPI

````yaml /api-reference/openapi.json get /v1/dev/user/folders
openapi: 3.1.0
info:
  contact:
    name: Omi
    url: https://omi.me/
  description: >-
    Programmatic access to your Omi data - memories, conversations, action
    items, goals, folders, and API keys. Build custom integrations, analytics
    dashboards, and automation workflows.
  license:
    name: MIT
    url: https://github.com/BasedHardware/omi/blob/main/LICENSE
  title: Omi Developer API
  version: 1.0.0
servers:
  - description: Production
    url: https://api.omi.me
security: []
tags:
  - description: Read and write user memories - timeless facts, preferences, and insights.
    name: Memories
  - description: Create and retrieve conversation transcripts with AI-generated summaries.
    name: Conversations
  - description: Retrieve user-defined folders for organizing conversations.
    name: Folders
  - description: Manage tasks and to-dos extracted from conversations or created manually.
    name: Action Items
  - description: Manage user goals and progress history.
    name: Goals
  - description: Create, list, and revoke developer API keys.
    name: API Keys
paths:
  /v1/dev/user/folders:
    get:
      tags:
        - Folders
      summary: Get User Folders
      description: >-
        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.
      operationId: listFolders
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/DeveloperFolder'
                title: Response Listfolders
                type: array
          description: Successful Response
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
      security:
        - developerApiKey: []
components:
  schemas:
    DeveloperFolder:
      properties:
        color:
          title: Color
          type: string
        conversation_count:
          default: 0
          title: Conversation Count
          type: integer
        created_at:
          format: date-time
          title: Created At
          type: string
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
        icon:
          title: Icon
          type: string
        id:
          title: Id
          type: string
        is_default:
          default: false
          title: Is Default
          type: boolean
        is_system:
          default: false
          title: Is System
          type: boolean
        name:
          title: Name
          type: string
        order:
          default: 0
          title: Order
          type: integer
        updated_at:
          format: date-time
          title: Updated At
          type: string
      required:
        - id
        - name
        - color
        - icon
        - created_at
        - updated_at
      title: DeveloperFolder
      type: object
    ErrorResponse:
      properties:
        detail:
          anyOf:
            - type: string
            - type: array
            - type: object
          description: Error detail returned by the API.
      required:
        - detail
      title: ErrorResponse
      type: object
  responses:
    Error401:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Missing or invalid authentication credentials.
    Error403:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Authenticated, but the token does not grant the required scope.
  securitySchemes:
    developerApiKey:
      bearerFormat: Omi Developer API key
      description: 'Send `Authorization: Bearer <omi_developer_api_key>`.'
      scheme: bearer
      type: http

````