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.
Endpoints List Folders
GET /v1/dev/user/folders Retrieve all folders for the authenticated user
This endpoint is strictly read-only. If the user has not yet had folders initialized, an empty array is returned. System folders (Work, Personal, Social) are created lazily through other paths — when the mobile app opens the conversations screen or when a new conversation is created. In normal usage, any user who can issue a Developer API key has already gone through one of those paths.
curl -H "Authorization: Bearer $API_KEY " \ "https://api.omi.me/v1/dev/user/folders"
import requests response = requests.get( "https://api.omi.me/v1/dev/user/folders" , headers = { "Authorization" : f "Bearer { API_KEY } " } ) folders = response.json()
const response = await fetch ( "https://api.omi.me/v1/dev/user/folders" , { headers: { Authorization: `Bearer ${ API_KEY } ` } } ); const folders = await response . json ();
[ { "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 }, { "id" : "folder_uuid_personal" , "name" : "Personal" , "description" : "Personal life, family, health, hobbies, and self-improvement" , "color" : "#10B981" , "icon" : "👤" , "created_at" : "2025-01-15T10:00:00Z" , "updated_at" : "2025-01-18T09:00:00Z" , "order" : 1 , "is_default" : false , "is_system" : true , "category_mapping" : "personal" , "conversation_count" : 7 }, { "id" : "folder_uuid_social" , "name" : "Social" , "description" : "Friends, social gatherings, entertainment, and casual conversations" , "color" : "#8B5CF6" , "icon" : "👥" , "created_at" : "2025-01-15T10:00:00Z" , "updated_at" : "2025-01-19T11:30:00Z" , "order" : 2 , "is_default" : false , "is_system" : true , "category_mapping" : "social" , "conversation_count" : 4 } ]
Field Type Description idstring Unique folder identifier namestring Display name of the folder descriptionstring | null Natural language description of what belongs in this folder colorstring Hex color code for the folder (e.g. #3B82F6) iconstring Emoji or icon identifier created_atdatetime When the folder was created updated_atdatetime When the folder was last updated orderinteger Display order index (lower = earlier) is_defaultboolean Whether this is the default folder for unassigned conversations is_systemboolean true for category-based system folders (Work, Personal, Social)category_mappingstring | null Maps to a conversation category for backwards compatibility conversation_countinteger Number of non-discarded conversations in this folder
Using Folder IDs to Filter Conversations Once you have folder IDs, you can filter conversations by folder using the folder_id query parameter on the conversations endpoint:
# Step 1: Get folder list FOLDERS = $( curl -s -H "Authorization: Bearer $API_KEY " \ "https://api.omi.me/v1/dev/user/folders" ) # Step 2: Extract the Work folder ID (using jq) WORK_FOLDER_ID = $( echo " $FOLDERS " | jq -r '.[] | select(.name=="Work") | .id' ) # Step 3: Fetch conversations in Work folder curl -H "Authorization: Bearer $API_KEY " \ "https://api.omi.me/v1/dev/user/conversations?folder_id= $WORK_FOLDER_ID "
import requests headers = { "Authorization" : f "Bearer { API_KEY } " } # Step 1: Get folder list folders = requests.get( "https://api.omi.me/v1/dev/user/folders" , headers = headers ).json() # Step 2: Find the Work folder work_folder = next ((f for f in folders if f[ "name" ] == "Work" ), None ) # Step 3: Fetch conversations in Work folder if work_folder: conversations = requests.get( "https://api.omi.me/v1/dev/user/conversations" , headers = headers, params = { "folder_id" : work_folder[ "id" ], "limit" : 50 } ).json() print ( f "Found { len (conversations) } work conversations" )
const headers = { Authorization: `Bearer ${ API_KEY } ` }; // Step 1: Get folder list const foldersRes = await fetch ( "https://api.omi.me/v1/dev/user/folders" , { headers } ); const folders = await foldersRes . json (); // Step 2: Find the Work folder const workFolder = folders . find ( f => f . name === "Work" ); // Step 3: Fetch conversations in Work folder if ( workFolder ) { const convsRes = await fetch ( `https://api.omi.me/v1/dev/user/conversations?folder_id= ${ workFolder . id } &limit=50` , { headers } ); const conversations = await convsRes . json (); console . log ( `Found ${ conversations . length } work conversations` ); }
You can also filter by starred=true to get only starred conversations, or combine both folder_id and starred to get starred conversations within a specific folder.