| title | Conversations |
|---|---|
| icon | message |
| description | Create and retrieve conversations via the Developer API |
Retrieve your conversation transcripts (only completed, non-discarded) | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `limit` | integer | 25 | Maximum number to return | | `offset` | integer | 0 | Number to skip | | `start_date` | datetime | - | Filter by start date (inclusive) | | `end_date` | datetime | - | Filter by end date (inclusive) | | `include_transcript` | boolean | false | Include full transcript segments | | `categories` | string | - | Comma-separated list of categories to filter by (e.g. `work,personal`). Matches conversations whose category is **any** of the listed values (OR semantics). | | `folder_id` | string | - | Filter by folder ID. Each conversation belongs to at most one folder, so this is a single-value filter. Must be a non-empty string if provided. Use `GET /v1/dev/user/folders` to retrieve folder IDs. | | `starred` | boolean | - | Filter by starred status. `true` for starred only, `false` for non-starred only. Omit to return all. | ```bash curl -H "Authorization: Bearer $API_KEY" \ "https://api.omi.me/v1/dev/user/conversations?limit=10&include_transcript=true" ``` ```python 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()
```
Create a new conversation from text with full AI processing | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `text` | string | **Yes** | The conversation text/transcript (1-100,000 characters) | | `text_source` | string | No | Source type: `audio_transcript`, `message`, or `other_text` (default: `other_text`) | | `text_source_spec` | string | No | Additional source info (e.g., 'email', 'slack', 'whatsapp') | | `started_at` | datetime | No | When conversation started (defaults to now) | | `finished_at` | datetime | No | When conversation finished (defaults to `started_at` + 5 minutes) | | `language` | string | No | Language code (default: 'en') | | `geolocation` | object | No | Geolocation data with `latitude` and `longitude` | ```bash 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" }' ``` ```python 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()
```
- **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
Create from structured transcript with speaker diarization | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `transcript_segments` | array | **Yes** | List of transcript segments (1-500 segments) | | `source` | string | No | Source of conversation (default: `external_integration`) | | `started_at` | datetime | No | When conversation started (defaults to now) | | `finished_at` | datetime | No | When conversation finished (calculated from last segment if not provided) | | `language` | string | No | Language code (default: 'en') | | `geolocation` | object | No | Geolocation data | | Field | Type | Required | Description | |-------|------|----------|-------------| | `text` | string | **Yes** | The spoken text | | `speaker` | string | No | Speaker identifier (e.g., 'SPEAKER_00', 'SPEAKER_01'). Default: 'SPEAKER_00' | | `speaker_id` | integer | No | Numeric speaker ID (auto-calculated if not provided) | | `is_user` | boolean | No | Whether this segment is from the user. Default: `false` | | `person_id` | string | No | ID of known person speaking | | `start` | float | **Yes** | Start time in seconds (e.g., 0.0, 1.5, 60.2) | | `end` | float | **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` ```bash 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" }' ``` ```python 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% from last quarter",
"speaker": "SPEAKER_01",
"is_user": False,
"start": 4.0,
"end": 7.2
}
],
"source": "phone",
"language": "en"
}
)
conversation = response.json()
```
Retrieve a single conversation by ID | Parameter | Type | Description | |-----------|------|-------------| | `conversation_id` | string | The ID of the conversation to retrieve | | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `include_transcript` | boolean | false | Include full transcript segments | ```bash curl -H "Authorization: Bearer $API_KEY" \ "https://api.omi.me/v1/dev/user/conversations/conv_456?include_transcript=true" ``` ```python 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()
```
Update a conversation's title or discard status | Parameter | Type | Description | |-----------|------|-------------| | `conversation_id` | string | The ID of the conversation to update | | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `title` | string | No | New title (1-500 characters) | | `discarded` | boolean | No | Whether the conversation is discarded |
At least one field must be provided.
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()
```
Delete a conversation permanently | Parameter | Type | Description | |-----------|------|-------------| | `conversation_id` | string | The ID of the conversation to delete | ```bash curl -X DELETE "https://api.omi.me/v1/dev/user/conversations/conv_456" \ -H "Authorization: Bearer $API_KEY" ``` ```python 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")
```
```python 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']}")
```
// 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}`);
```
```bash #!/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"
```
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")
```
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();
```