Skip to main content

Endpoints

GET

Retrieve conversations

GET Single

Get one conversation

POST

Create from text

PATCH

Update conversation

DELETE

Delete conversation

POST Segments

Create from transcript

Get Conversations

GET /v1/dev/user/conversations

Retrieve your conversation transcripts (only completed, non-discarded)

Query Parameters

ParameterTypeDefaultDescription
limitinteger25Maximum number to return
offsetinteger0Number to skip
start_datedatetime-Filter by start date (inclusive)
end_datedatetime-Filter by end date (inclusive)
include_transcriptbooleanfalseInclude full transcript segments
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.omi.me/v1/dev/user/conversations?limit=10&include_transcript=true"

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": []
    }
  }
]
[
  {
    "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
      }
    ]
  }
]
FieldTypeDescription
idstringUnique identifier
created_atdatetimeWhen the conversation record was created
started_atdatetimeWhen the conversation started
finished_atdatetimeWhen the conversation ended
languagestringLanguage code (e.g., “en”)
sourcestringSource device/app
structuredobjectAI-generated structured data
transcript_segmentsarrayTranscript segments (if include_transcript=true)
FieldTypeDescription
titlestringAI-generated title
overviewstringSummary of the conversation
emojistringRepresentative emoji
categorystringCategory (work, personal, etc.)
action_itemsarrayExtracted action items
eventsarrayExtracted calendar events

Create Conversation from Text

POST /v1/dev/user/conversations

Create a new conversation from text with full AI processing

Request Body

ParameterTypeRequiredDescription
textstringYesThe conversation text/transcript (1-100,000 characters)
text_sourcestringNoSource type: audio_transcript, message, or other_text (default: other_text)
text_source_specstringNoAdditional source info (e.g., ‘email’, ‘slack’, ‘whatsapp’)
started_atdatetimeNoWhen conversation started (defaults to now)
finished_atdatetimeNoWhen conversation finished (defaults to started_at + 5 minutes)
languagestringNoLanguage code (default: ‘en’)
geolocationobjectNoGeolocation 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"
  }'

Response Example

{
  "id": "conv_456",
  "status": "completed",
  "discarded": false
}

Processing Pipeline

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

Request Body

ParameterTypeRequiredDescription
transcript_segmentsarrayYesList of transcript segments (1-500 segments)
sourcestringNoSource of conversation (default: external_integration)
started_atdatetimeNoWhen conversation started (defaults to now)
finished_atdatetimeNoWhen conversation finished (calculated from last segment if not provided)
languagestringNoLanguage code (default: ‘en’)
geolocationobjectNoGeolocation data
FieldTypeRequiredDescription
textstringYesThe spoken text
speakerstringNoSpeaker identifier (e.g., ‘SPEAKER_00’, ‘SPEAKER_01’). Default: ‘SPEAKER_00’
speaker_idintegerNoNumeric speaker ID (auto-calculated if not provided)
is_userbooleanNoWhether this segment is from the user. Default: false
person_idstringNoID of known person speaking
startfloatYesStart time in seconds (e.g., 0.0, 1.5, 60.2)
endfloatYesEnd 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"
  }'

Response Example

{
  "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

Path Parameters

ParameterTypeDescription
conversation_idstringThe ID of the conversation to retrieve

Query Parameters

ParameterTypeDefaultDescription
include_transcriptbooleanfalseInclude full transcript segments
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.omi.me/v1/dev/user/conversations/conv_456?include_transcript=true"

Response Example

{
  "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

Path Parameters

ParameterTypeDescription
conversation_idstringThe ID of the conversation to update

Request Body

ParameterTypeRequiredDescription
titlestringNoNew title (1-500 characters)
discardedbooleanNoWhether 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"
  }'

Response Example

{
  "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

Path Parameters

ParameterTypeDescription
conversation_idstringThe ID of the conversation to delete
curl -X DELETE "https://api.omi.me/v1/dev/user/conversations/conv_456" \
  -H "Authorization: Bearer $API_KEY"

Response Example

{
  "success": true
}
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']}")

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"