Endpoints
GET Retrieve conversations
GET Single Get one conversation
DELETE Delete conversation
POST Segments Create from transcript
Get Conversations
GET /v1/dev/user/conversations Retrieve your conversation transcripts (only completed, non-discarded)
Parameter Type Default Description limitinteger 25 Maximum number to return offsetinteger 0 Number to skip start_datedatetime - Filter by start date (inclusive) end_datedatetime - Filter by end date (inclusive) include_transcriptboolean false Include full transcript segments
curl -H "Authorization: Bearer $API_KEY " \
"https://api.omi.me/v1/dev/user/conversations?limit=10&include_transcript=true"
import requests
response = requests.get(
"https://api.omi.me/v1/dev/user/conversations" ,
headers = { "Authorization" : f "Bearer { API_KEY } " },
params = { "limit" : 10 , "include_transcript" : True }
)
conversations = response.json()
const response = await fetch (
"https://api.omi.me/v1/dev/user/conversations?limit=10&include_transcript=true" ,
{ headers: { Authorization: `Bearer ${ API_KEY } ` } }
);
const conversations = await response . json ();
Response (without transcript)
[
{
"id" : "conv_202" ,
"created_at" : "2025-01-20T13:50:00Z" ,
"started_at" : "2025-01-20T13:50:00Z" ,
"finished_at" : "2025-01-20T14:10:00Z" ,
"language" : "en" ,
"source" : "omi" ,
"structured" : {
"title" : "Feature Discussion" ,
"overview" : "Brainstorming session for new features" ,
"emoji" : "💼" ,
"category" : "business" ,
"action_items" : [
{
"description" : "Create mockups for new UI" ,
"completed" : false ,
"created_at" : "2025-01-20T14:10:00Z" ,
"updated_at" : "2025-01-20T14:10:00Z" ,
"due_at" : null ,
"completed_at" : null
}
],
"events" : []
}
}
]
Response (with transcript)
[
{
"id" : "conv_202" ,
"created_at" : "2025-01-20T13:50:00Z" ,
"started_at" : "2025-01-20T13:50:00Z" ,
"finished_at" : "2025-01-20T14:10:00Z" ,
"language" : "en" ,
"source" : "phone" ,
"structured" : {
"title" : "Feature Discussion" ,
"overview" : "Brainstorming session for new features" ,
"emoji" : "💼" ,
"category" : "business" ,
"action_items" : [],
"events" : []
},
"transcript_segments" : [
{
"id" : "seg_001" ,
"text" : "Let's discuss the new feature" ,
"speaker_id" : 0 ,
"start" : 0.0 ,
"end" : 2.5
},
{
"id" : "seg_002" ,
"text" : "I think we should focus on the user interface first" ,
"speaker_id" : 1 ,
"start" : 2.5 ,
"end" : 5.8
}
]
}
]
Field Type Description idstring Unique identifier created_atdatetime When the conversation record was created started_atdatetime When the conversation started finished_atdatetime When the conversation ended languagestring Language code (e.g., “en”) sourcestring Source device/app structuredobject AI-generated structured data transcript_segmentsarray Transcript segments (if include_transcript=true)
Field Type Description titlestring AI-generated title overviewstring Summary of the conversation emojistring Representative emoji categorystring Category (work, personal, etc.) action_itemsarray Extracted action items eventsarray Extracted calendar events
Create Conversation from Text
POST /v1/dev/user/conversations Create a new conversation from text with full AI processing
Parameter Type Required Description textstring Yes The conversation text/transcript (1-100,000 characters) text_sourcestring No Source type: audio_transcript, message, or other_text (default: other_text) text_source_specstring No Additional source info (e.g., ‘email’, ‘slack’, ‘whatsapp’) started_atdatetime No When conversation started (defaults to now) finished_atdatetime No When conversation finished (defaults to started_at + 5 minutes) languagestring No Language code (default: ‘en’) geolocationobject No Geolocation data with latitude and longitude
curl -X POST "https://api.omi.me/v1/dev/user/conversations" \
-H "Authorization: Bearer $API_KEY " \
-H "Content-Type: application/json" \
-d '{
"text": "Meeting notes: Discussed Q1 goals. Action item: prepare budget by Friday.",
"text_source": "other_text",
"text_source_spec": "meeting_notes",
"started_at": "2025-12-06T14:00:00+00:00",
"language": "en"
}'
import requests
response = requests.post(
"https://api.omi.me/v1/dev/user/conversations" ,
headers = {
"Authorization" : f "Bearer { API_KEY } " ,
"Content-Type" : "application/json"
},
json = {
"text" : "Meeting notes: Discussed Q1 goals. Action item: prepare budget by Friday." ,
"text_source" : "other_text" ,
"text_source_spec" : "meeting_notes" ,
"started_at" : "2025-12-06T14:00:00+00:00" ,
"language" : "en"
}
)
conversation = response.json()
const response = await fetch (
"https://api.omi.me/v1/dev/user/conversations" ,
{
method: "POST" ,
headers: {
Authorization: `Bearer ${ API_KEY } ` ,
"Content-Type" : "application/json"
},
body: JSON . stringify ({
text: "Meeting notes: Discussed Q1 goals. Action item: prepare budget by Friday." ,
text_source: "other_text" ,
text_source_spec: "meeting_notes" ,
started_at: "2025-12-06T14:00:00+00:00" ,
language: "en"
})
}
);
const conversation = await response . json ();
{
"id" : "conv_456" ,
"status" : "completed" ,
"discarded" : false
}
When you create a conversation, the following happens automatically:
Discard Detection : Determines if content is meaningful enough to save
Structured Generation : Creates title, overview, category, and emoji
Action Item Extraction : Identifies and creates action items (with deduplication against past 2 days)
Memory Extraction : Extracts interesting facts and insights (up to 4 per conversation)
App Integration : Triggers enabled summarization apps
Webhooks : Notifies external systems
Memories and action items are extracted asynchronously. Use the GET endpoints to retrieve them after creation.
Create Conversation from Transcript Segments
POST /v1/dev/user/conversations/from-segments Create from structured transcript with speaker diarization
Parameter Type Required Description transcript_segmentsarray Yes List of transcript segments (1-500 segments) sourcestring No Source of conversation (default: external_integration) started_atdatetime No When conversation started (defaults to now) finished_atdatetime No When conversation finished (calculated from last segment if not provided) languagestring No Language code (default: ‘en’) geolocationobject No Geolocation data
Transcript Segment Fields
Field Type Required Description textstring Yes The spoken text speakerstring No Speaker identifier (e.g., ‘SPEAKER_00’, ‘SPEAKER_01’). Default: ‘SPEAKER_00’ speaker_idinteger No Numeric speaker ID (auto-calculated if not provided) is_userboolean No Whether this segment is from the user. Default: false person_idstring No ID of known person speaking startfloat Yes Start time in seconds (e.g., 0.0, 1.5, 60.2) endfloat Yes End time in seconds (e.g., 1.5, 3.0, 65.8)
omi, friend, openglass, phone, desktop, apple_watch, bee, plaud, frame, screenpipe, workflow, sdcard, external_integration
curl -X POST "https://api.omi.me/v1/dev/user/conversations/from-segments" \
-H "Authorization: Bearer $API_KEY " \
-H "Content-Type: application/json" \
-d '{
"transcript_segments": [
{
"text": "Let' \' 's review the quarterly results",
"speaker": "SPEAKER_00",
"is_user": true,
"start": 0.0,
"end": 3.5
},
{
"text": "Revenue is up 25% from last quarter",
"speaker": "SPEAKER_01",
"is_user": false,
"start": 4.0,
"end": 7.2
}
],
"source": "phone",
"language": "en"
}'
import requests
response = requests.post(
"https://api.omi.me/v1/dev/user/conversations/from-segments" ,
headers = {
"Authorization" : f "Bearer { API_KEY } " ,
"Content-Type" : "application/json"
},
json = {
"transcript_segments" : [
{
"text" : "Let's review the quarterly results" ,
"speaker" : "SPEAKER_00" ,
"is_user" : True ,
"start" : 0.0 ,
"end" : 3.5
},
{
"text" : "Revenue is up 25 % f rom last quarter" ,
"speaker" : "SPEAKER_01" ,
"is_user" : False ,
"start" : 4.0 ,
"end" : 7.2
}
],
"source" : "phone" ,
"language" : "en"
}
)
conversation = response.json()
const response = await fetch (
"https://api.omi.me/v1/dev/user/conversations/from-segments" ,
{
method: "POST" ,
headers: {
Authorization: `Bearer ${ API_KEY } ` ,
"Content-Type" : "application/json"
},
body: JSON . stringify ({
transcript_segments: [
{
text: "Let's review the quarterly results" ,
speaker: "SPEAKER_00" ,
is_user: true ,
start: 0.0 ,
end: 3.5
},
{
text: "Revenue is up 25% from last quarter" ,
speaker: "SPEAKER_01" ,
is_user: false ,
start: 4.0 ,
end: 7.2
}
],
source: "phone" ,
language: "en"
})
}
);
const conversation = await response . json ();
{
"id" : "conv_789" ,
"status" : "completed" ,
"discarded" : false
}
Unlike text-based conversations, transcript segments ARE stored in the transcript_segments field and can be retrieved with include_transcript=true.
Get Single Conversation
GET /v1/dev/user/conversations/{conversation_id} Retrieve a single conversation by ID
Parameter Type Description conversation_idstring The ID of the conversation to retrieve
Parameter Type Default Description include_transcriptboolean false Include full transcript segments
curl -H "Authorization: Bearer $API_KEY " \
"https://api.omi.me/v1/dev/user/conversations/conv_456?include_transcript=true"
import requests
response = requests.get(
"https://api.omi.me/v1/dev/user/conversations/conv_456" ,
headers = { "Authorization" : f "Bearer { API_KEY } " },
params = { "include_transcript" : True }
)
conversation = response.json()
const response = await fetch (
"https://api.omi.me/v1/dev/user/conversations/conv_456?include_transcript=true" ,
{ headers: { Authorization: `Bearer ${ API_KEY } ` } }
);
const conversation = await response . json ();
{
"id" : "conv_456" ,
"created_at" : "2025-01-20T13:50:00Z" ,
"started_at" : "2025-01-20T13:50:00Z" ,
"finished_at" : "2025-01-20T14:10:00Z" ,
"language" : "en" ,
"source" : "external_integration" ,
"structured" : {
"title" : "Q1 Goals Discussion" ,
"overview" : "Meeting to discuss quarterly goals and budget preparation" ,
"emoji" : "📊" ,
"category" : "business" ,
"action_items" : [
{
"description" : "Prepare budget by Friday" ,
"completed" : false
}
],
"events" : []
}
}
Update Conversation
PATCH /v1/dev/user/conversations/{conversation_id} Update a conversation’s title or discard status
Parameter Type Description conversation_idstring The ID of the conversation to update
Parameter Type Required Description titlestring No New title (1-500 characters) discardedboolean No Whether the conversation is discarded
At least one field must be provided.
curl -X PATCH "https://api.omi.me/v1/dev/user/conversations/conv_456" \
-H "Authorization: Bearer $API_KEY " \
-H "Content-Type: application/json" \
-d '{
"title": "Q1 Planning Meeting - Budget Discussion"
}'
import requests
response = requests.patch(
"https://api.omi.me/v1/dev/user/conversations/conv_456" ,
headers = {
"Authorization" : f "Bearer { API_KEY } " ,
"Content-Type" : "application/json"
},
json = { "title" : "Q1 Planning Meeting - Budget Discussion" }
)
conversation = response.json()
const response = await fetch (
"https://api.omi.me/v1/dev/user/conversations/conv_456" ,
{
method: "PATCH" ,
headers: {
Authorization: `Bearer ${ API_KEY } ` ,
"Content-Type" : "application/json"
},
body: JSON . stringify ({
title: "Q1 Planning Meeting - Budget Discussion"
})
}
);
const conversation = await response . json ();
{
"id" : "conv_456" ,
"created_at" : "2025-01-20T13:50:00Z" ,
"started_at" : "2025-01-20T13:50:00Z" ,
"finished_at" : "2025-01-20T14:10:00Z" ,
"language" : "en" ,
"source" : "external_integration" ,
"structured" : {
"title" : "Q1 Planning Meeting - Budget Discussion" ,
"overview" : "Meeting to discuss quarterly goals and budget preparation" ,
"emoji" : "📊" ,
"category" : "business" ,
"action_items" : [],
"events" : []
}
}
Use discarded: true to hide a conversation from the main list without permanently deleting it.
Delete Conversation
DELETE /v1/dev/user/conversations/{conversation_id} Delete a conversation permanently
Parameter Type Description conversation_idstring The ID of the conversation to delete
curl -X DELETE "https://api.omi.me/v1/dev/user/conversations/conv_456" \
-H "Authorization: Bearer $API_KEY "
import requests
response = requests.delete(
"https://api.omi.me/v1/dev/user/conversations/conv_456" ,
headers = { "Authorization" : f "Bearer { API_KEY } " }
)
result = response.json()
if result[ "success" ]:
print ( "Conversation deleted successfully" )
const response = await fetch (
"https://api.omi.me/v1/dev/user/conversations/conv_456" ,
{
method: "DELETE" ,
headers: { Authorization: `Bearer ${ API_KEY } ` }
}
);
const result = await response . json ();
if ( result . success ) {
console . log ( "Conversation deleted successfully" );
}
This action is permanent. Deleted conversations and their associated photos cannot be recovered. Consider using PATCH with discarded: true to hide a conversation instead.
Use Case: Upload Meeting Transcript
import requests
from datetime import datetime, timezone
API_KEY = "omi_dev_your_api_key"
# Your meeting transcript with speaker diarization
transcript = [
{ "speaker" : "SPEAKER_00" , "text" : "Welcome everyone to the standup" , "start" : 0.0 , "end" : 2.5 },
{ "speaker" : "SPEAKER_01" , "text" : "Thanks. I finished the API integration yesterday" , "start" : 3.0 , "end" : 6.2 },
{ "speaker" : "SPEAKER_00" , "text" : "Great work! Any blockers?" , "start" : 6.5 , "end" : 8.0 },
{ "speaker" : "SPEAKER_01" , "text" : "Just waiting on the design review" , "start" : 8.3 , "end" : 10.5 },
]
# Convert to Omi format
segments = [
{
"text" : seg[ "text" ],
"speaker" : seg[ "speaker" ],
"is_user" : seg[ "speaker" ] == "SPEAKER_00" ,
"start" : seg[ "start" ],
"end" : seg[ "end" ]
}
for seg in transcript
]
# Create conversation
response = requests.post(
"https://api.omi.me/v1/dev/user/conversations/from-segments" ,
headers = {
"Authorization" : f "Bearer { API_KEY } " ,
"Content-Type" : "application/json"
},
json = {
"transcript_segments" : segments,
"source" : "phone" ,
"started_at" : datetime.now(timezone.utc).isoformat(),
"language" : "en"
}
)
result = response.json()
print ( f "Created conversation: { result[ 'id' ] } " )
print ( f "Status: { result[ 'status' ] } " )
print ( f "Discarded: { result[ 'discarded' ] } " )
const API_KEY = process . env . OMI_API_KEY ;
// Your meeting transcript with speaker diarization
const transcript = [
{ speaker: "SPEAKER_00" , text: "Welcome everyone to the standup" , start: 0.0 , end: 2.5 },
{ speaker: "SPEAKER_01" , text: "Thanks. I finished the API integration yesterday" , start: 3.0 , end: 6.2 },
{ speaker: "SPEAKER_00" , text: "Great work! Any blockers?" , start: 6.5 , end: 8.0 },
{ speaker: "SPEAKER_01" , text: "Just waiting on the design review" , start: 8.3 , end: 10.5 },
];
// Convert to Omi format
const segments = transcript . map ( seg => ({
text: seg . text ,
speaker: seg . speaker ,
is_user: seg . speaker === "SPEAKER_00" ,
start: seg . start ,
end: seg . end
}));
// Create conversation
const response = await fetch (
"https://api.omi.me/v1/dev/user/conversations/from-segments" ,
{
method: "POST" ,
headers: {
Authorization: `Bearer ${ API_KEY } ` ,
"Content-Type" : "application/json"
},
body: JSON . stringify ({
transcript_segments: segments ,
source: "phone" ,
started_at: new Date (). toISOString (),
language: "en"
})
}
);
const result = await response . json ();
console . log ( `Created conversation: ${ result . id } ` );
console . log ( `Status: ${ result . status } ` );
console . log ( `Discarded: ${ result . discarded } ` );
Use Case: Export Conversations
#!/bin/bash
API_KEY = "omi_dev_your_api_key"
# Export all conversations with transcripts
curl -H "Authorization: Bearer $API_KEY " \
"https://api.omi.me/v1/dev/user/conversations?limit=1000&include_transcript=true" \
> conversations_backup.json
echo "Exported conversations to conversations_backup.json"
import requests
import json
API_KEY = "omi_dev_your_api_key"
# Paginate through all conversations
all_conversations = []
offset = 0
limit = 100
while True :
response = requests.get(
"https://api.omi.me/v1/dev/user/conversations" ,
headers = { "Authorization" : f "Bearer { API_KEY } " },
params = {
"limit" : limit,
"offset" : offset,
"include_transcript" : True
}
)
conversations = response.json()
if not conversations:
break
all_conversations.extend(conversations)
offset += limit
print ( f "Fetched { len (all_conversations) } conversations..." )
# Save to file
with open ( "conversations_backup.json" , "w" ) as f:
json.dump(all_conversations, f, indent = 2 )
print ( f "Exported { len (all_conversations) } conversations" )
const fs = require ( 'fs' );
const API_KEY = process . env . OMI_API_KEY ;
async function exportConversations () {
const allConversations = [];
let offset = 0 ;
const limit = 100 ;
while ( true ) {
const response = await fetch (
`https://api.omi.me/v1/dev/user/conversations?limit= ${ limit } &offset= ${ offset } &include_transcript=true` ,
{ headers: { Authorization: `Bearer ${ API_KEY } ` } }
);
const conversations = await response . json ();
if ( conversations . length === 0 ) break ;
allConversations . push ( ... conversations );
offset += limit ;
console . log ( `Fetched ${ allConversations . length } conversations...` );
}
fs . writeFileSync (
'conversations_backup.json' ,
JSON . stringify ( allConversations , null , 2 )
);
console . log ( `Exported ${ allConversations . length } conversations` );
}
exportConversations ();