Data Import APIs

Omi’s Data Import APIs allow your app to programmatically interact with user data in the Omi ecosystem. Unlike triggers (which respond to events), these APIs let your app proactively create or read data.

Create Conversation

Add new conversations to a user’s account from external sources

Create Memories

Add facts and knowledge to the user’s memory bank

Read Conversations

Access and retrieve a user’s conversation history

Read Memories

Access facts stored in the user’s knowledge base

Quick Reference

Capability	Method	Endpoint
Create Conversation	`POST`	`/v2/integrations/{app_id}/user/conversations?uid={user_id}`
Create Memories	`POST`	`/v2/integrations/{app_id}/user/memories?uid={user_id}`
Read Conversations	`GET`	`/v2/integrations/{app_id}/conversations?uid={user_id}`
Read Memories	`GET`	`/v2/integrations/{app_id}/memories?uid={user_id}`

Base URL: https://api.omi.me

Prerequisites

Understand Omi App Basics

Familiarize yourself with Omi app development and integration apps

Create Your App

In the Omi mobile app:

Go to Apps → Create App
Under App Capabilities, select External Integration
Select Imports and choose the specific capabilities your app needs

Generate API Keys

Go to your app’s management page, find the API Keys section, and click Create Key

Copy and store your API key securely - you won’t be able to see it again!

User Enables Your App

The user must explicitly enable your app in their Omi account before you can access their data

Authentication

All API requests require authentication using your API key in the Authorization header:

Authorization: Bearer sk_your_api_key_here

The API key must belong to the app specified in the URL path (app_id).

Create Conversation API

Create new conversations in a user’s Omi account from external sources like phone calls, emails, or messages.

Endpoint

POST https://api.omi.me/v2/integrations/{app_id}/user/conversations?uid={user_id}

Request Body

{
  "text": "The full text content of the conversation",
  "started_at": "2024-07-21T22:34:43.384323+00:00",
  "finished_at": "2024-07-21T22:35:43.384323+00:00",
  "text_source": "audio_transcript",
  "text_source_spec": "phone_call",
  "language": "en",
  "geolocation": {
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

Field Reference

Field	Required	Default	Description
`text`	Yes	-	The full text content of the conversation
`started_at`	No	Current time	When the conversation started (ISO 8601)
`finished_at`	No	started_at + 5min	When the conversation ended (ISO 8601)
`text_source`	No	`audio_transcript`	Source type: `audio_transcript`, `message`, or `other_text`
`text_source_spec`	No	-	Additional source detail (e.g., `phone_call`, `sms`, `email`)
`language`	No	`en`	Language code
`geolocation`	No	-	Object with `latitude` and `longitude` coordinates

Response

Success (200 OK):

{}

The conversation is created asynchronously in the user’s account.

Example: Phone Call Transcript

import requests
from datetime import datetime, timezone

response = requests.post(
    f"https://api.omi.me/v2/integrations/{APP_ID}/user/conversations?uid={USER_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "started_at": datetime.now(timezone.utc).isoformat(),
        "finished_at": datetime.now(timezone.utc).isoformat(),
        "text": "John: Hi Sarah, how was your weekend?\n\nSarah: It was great! I went hiking.",
        "text_source": "audio_transcript",
        "text_source_spec": "phone_call"
    }
)

Example: Text Messages

response = requests.post(
    f"https://api.omi.me/v2/integrations/{APP_ID}/user/conversations?uid={USER_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "text": "Mom: Don't forget to pick up milk\n\nMe: Will do!",
        "text_source": "message",
        "text_source_spec": "sms"
    }
)

Example: Email

response = requests.post(
    f"https://api.omi.me/v2/integrations/{APP_ID}/user/conversations?uid={USER_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "text": "From: alex@example.com\nSubject: Dinner Plans\n\nWould you like to grab dinner Friday at 7pm?",
        "text_source": "other_text",
        "text_source_spec": "email"
    }
)

response = requests.post(
    f"https://api.omi.me/v2/integrations/{APP_ID}/user/conversations?uid={USER_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "text": "Just finished my first marathon! 26.2 miles in 4:15. #running",
        "text_source": "other_text",
        "text_source_spec": "social_post",
        "geolocation": {"latitude": 40.7128, "longitude": -74.0060}
    }
)

Create Memories API

Add facts and knowledge to a user’s memory bank. You can either provide raw text (Omi will extract memories automatically) or provide explicit memory objects.

Endpoint

POST https://api.omi.me/v2/integrations/{app_id}/user/memories?uid={user_id}

Request Options

Extract from Text
Explicit Memories

Provide raw text and let Omi automatically extract relevant memories:

{
  "text": "Your flight to Paris has been confirmed for May 15th, 2024. Departure: JFK at 9:30 PM.",
  "text_source": "email",
  "text_source_spec": "travel_confirmation"
}

Field	Required	Default	Description
`text`	Yes*	-	Text content from which memories will be extracted
`text_source`	No	`other`	Source type: `email`, `social_post`, or `other`
`text_source_spec`	No	-	Additional source detail

*Either text or memories is required

Provide structured memory objects directly:

{
  "memories": [
    {
      "content": "User is allergic to peanuts and shellfish",
      "tags": ["health", "allergies", "important"]
    },
    {
      "content": "User's mother's birthday is on August 15th",
      "tags": ["family", "dates"]
    }
  ],
  "text_source": "other",
  "text_source_spec": "user_profile"
}

Field	Required	Description
`memories`	Yes*	Array of memory objects
`memories[].content`	Yes	The memory content
`memories[].tags`	No	Array of categorization tags

*Either text or memories is required

Response

Success (200 OK):

{}

Memories are extracted/saved asynchronously in the user’s account.

Example: Extract from Email

response = requests.post(
    f"https://api.omi.me/v2/integrations/{APP_ID}/user/memories?uid={USER_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "text": "Your flight to Paris confirmed for May 15th. Departure: JFK 9:30 PM. Hotel de Paris: May 16-20.",
        "text_source": "email",
        "text_source_spec": "travel_confirmation"
    }
)

Example: Explicit User Preferences

response = requests.post(
    f"https://api.omi.me/v2/integrations/{APP_ID}/user/memories?uid={USER_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "memories": [
            {"content": "User prefers window seats when flying", "tags": ["preferences", "travel"]},
            {"content": "User is vegetarian", "tags": ["preferences", "food"]}
        ]
    }
)

Read Conversations API

Retrieve conversations from a user’s Omi account.

Endpoint

GET https://api.omi.me/v2/integrations/{app_id}/conversations?uid={user_id}

Query Parameters

Parameter	Default	Description
`limit`	100	Maximum conversations to return (max: 1000)
`offset`	0	Number to skip for pagination
`include_discarded`	false	Include discarded conversations
`statuses`	-	Filter by statuses (comma-separated)

Response

{
  "conversations": [
    {
      "id": "conversation_id_1",
      "created_at": "2024-03-15T12:00:00Z",
      "started_at": "2024-03-15T12:00:00Z",
      "finished_at": "2024-03-15T12:05:00Z",
      "text": "Full conversation text content...",
      "structured": {
        "title": "Conversation Title",
        "overview": "Brief overview of the conversation"
      },
      "transcript_segments": [
        {"text": "Segment text...", "start_time": 0, "end_time": 10}
      ],
      "geolocation": {"latitude": 37.7749, "longitude": -122.4194}
    }
  ]
}

Example: Paginated Retrieval

response = requests.get(
    f"https://api.omi.me/v2/integrations/{APP_ID}/conversations?uid={USER_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 50, "offset": 0}
)

conversations = response.json()["conversations"]
for conv in conversations:
    print(f"{conv['structured']['title']} - {conv['created_at']}")

Read Memories API

Retrieve memories (facts) from a user’s knowledge base.

Endpoint

GET https://api.omi.me/v2/integrations/{app_id}/memories?uid={user_id}

Query Parameters

Parameter	Default	Description
`limit`	100	Maximum memories to return (max: 1000)
`offset`	0	Number to skip for pagination

Response

{
  "memories": [
    {
      "id": "memory_id_1",
      "content": "User prefers vegetarian food options",
      "created_at": "2024-03-15T12:00:00Z",
      "tags": ["preferences", "food"]
    }
  ]
}

Example: Retrieve All Memories

response = requests.get(
    f"https://api.omi.me/v2/integrations/{APP_ID}/memories?uid={USER_ID}",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={"limit": 100}
)

memories = response.json()["memories"]
for memory in memories:
    print(f"{memory['content']} (Tags: {', '.join(memory.get('tags', []))})")

Error Handling

All endpoints return consistent error codes:

Status	Error	Description
400	Bad Request	Invalid request format or missing required fields
401	Unauthorized	Missing or invalid `Authorization` header
403	Forbidden	Invalid API key, app not enabled by user, or app lacks required capability
404	Not Found	App not found
422	Unprocessable Entity	Valid format but invalid content (e.g., empty text and memories)
429	Too Many Requests	Rate limit exceeded - implement exponential backoff

Implement exponential backoff when you receive a 429 error. Start with a 1-second delay and double it on each retry.

Best Practices

Get User Consent

Always ensure you have explicit user consent before creating conversations or memories on their behalf

Secure API Keys

Store API keys securely using environment variables or secret management systems - never hardcode them

Handle Errors Gracefully

Implement robust error handling with retries and logging for production reliability

Quality Over Quantity

Only create meaningful content that provides genuine value to users - avoid spam

Example Use Cases

Journal Creator

Automatically create conversation entries from a journaling app, syncing daily reflections to Omi

Meeting Summarizer

Create structured conversation summaries after calendar meetings end, including action items

Health Tracker

Generate conversations with health insights from fitness tracker data

Knowledge Base Builder

Extract memories from educational content or research materials to build a personal knowledge base

Contact Manager

Extract and store contact details as memories from emails and messages

Analytics Dashboard

Read conversations and memories to generate insights and visualizations about user patterns

Testing & Troubleshooting

Use Development Keys

Create a separate API key for testing to avoid affecting production data

Mark Test Content

Clearly mark test conversations (e.g., prefix with “[TEST]”) so they’re easy to identify and clean up

Verify in the Omi App

After creating content, open the Omi app to verify it appears correctly

Check Structured Data

For conversations, verify that title, overview, and action items are extracted correctly

Common Issues:

Problem	Solution
Authentication errors	Verify your API key is correct and matches the app_id in the URL
Permission errors	Ensure the user has enabled your app and your app has the required capability
Empty response	Check that you’re providing `text` or `memories` (for memory creation)
Rate limiting	Implement exponential backoff starting at 1 second

Capabilities

The Import API supports creating and updating conversations, memories, and action items. See the API Reference for the full endpoint list.

Developer API

Access your own personal Omi data programmatically

Integration Apps

Learn about building integration apps with triggers

Submit Your App

Guidelines for submitting your app to the Omi store

Chat Tools

Add custom tools to Omi’s AI chat

Getting Started

Examples

Data Import APIs

Create Conversation

Create Memories

Read Conversations

Read Memories

Quick Reference

Prerequisites

Authentication

Create Conversation API

Endpoint

Request Body

Field Reference

Response

Create Memories API

Endpoint

Request Options

Response

Read Conversations API

Endpoint

Query Parameters

Response

Read Memories API

Endpoint

Query Parameters

Response

Error Handling

Best Practices

Get User Consent

Secure API Keys

Handle Errors Gracefully

Quality Over Quantity

Example Use Cases

Testing & Troubleshooting

Capabilities

Developer API

Integration Apps

Submit Your App

Chat Tools

Create Conversation

Create Memories

Read Conversations

Read Memories

​Quick Reference

​Prerequisites

​Authentication

​Create Conversation API

​Endpoint

​Request Body

​Field Reference

​Response

​Create Memories API

​Endpoint

​Request Options

​Response

​Read Conversations API

​Endpoint

​Query Parameters

​Response

​Read Memories API

​Endpoint

​Query Parameters

​Response

​Error Handling

​Best Practices

Get User Consent

Secure API Keys

Handle Errors Gracefully

Quality Over Quantity

​Example Use Cases

​Testing & Troubleshooting

​Capabilities

​Related

Developer API

Integration Apps

Submit Your App

Chat Tools

Quick Reference

Prerequisites

Authentication

Create Conversation API

Endpoint

Request Body

Field Reference

Response

Create Memories API

Endpoint

Request Options

Response

Read Conversations API

Endpoint

Query Parameters

Response

Read Memories API

Endpoint

Query Parameters

Response

Error Handling

Best Practices

Example Use Cases

Testing & Troubleshooting

Capabilities

Related