omi/docs/doc/developer/apps/Import.mdx at main · ghzhost/omi

title	Data Import APIs
icon	file-import
description	Programmatically create and read conversations and memories in users' Omi accounts using the Integration 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.

Add new conversations to a user's account from external sources Add facts and knowledge to the user's memory bank Access and retrieve a user's conversation history 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

Familiarize yourself with [Omi app development](/doc/developer/apps/Introduction) and [integration apps](/doc/developer/apps/Integrations) In the Omi mobile app: 1. Go to **Apps** → **Create App** 2. Under **App Capabilities**, select **External Integration** 3. Select **Imports** and choose the specific capabilities your app needs Go to your app's management page, find the **API Keys** section, and click **Create Key**

<Warning>Copy and store your API key securely - you won't be able to see it again!</Warning>

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.

```python 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"
    }
)
```

```python 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" } ) ``` ```python 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" } ) ``` ```python 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

Provide raw text and let Omi automatically extract relevant memories:

```json
{
  "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:

```json
{
  "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.

```python 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" } ) ``` ```python 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}
    }
  ]
}

```python 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']}")

</Accordion>

---

## 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

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

```python 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', []))})")

</Accordion>

---

## 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 |

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

---

## Best Practices

<CardGroup cols={2}>
  <Card title="Get User Consent" icon="user-check">
    Always ensure you have explicit user consent before creating conversations or memories on their behalf
  </Card>
  <Card title="Secure API Keys" icon="key">
    Store API keys securely using environment variables or secret management systems - never hardcode them
  </Card>
  <Card title="Handle Errors Gracefully" icon="shield-check">
    Implement robust error handling with retries and logging for production reliability
  </Card>
  <Card title="Quality Over Quantity" icon="star">
    Only create meaningful content that provides genuine value to users - avoid spam
  </Card>
</CardGroup>

---

## Example Use Cases

<AccordionGroup>
  <Accordion title="Journal Creator" icon="book">
    Automatically create conversation entries from a journaling app, syncing daily reflections to Omi
  </Accordion>
  <Accordion title="Meeting Summarizer" icon="calendar">
    Create structured conversation summaries after calendar meetings end, including action items
  </Accordion>
  <Accordion title="Health Tracker" icon="heart-pulse">
    Generate conversations with health insights from fitness tracker data
  </Accordion>
  <Accordion title="Knowledge Base Builder" icon="graduation-cap">
    Extract memories from educational content or research materials to build a personal knowledge base
  </Accordion>
  <Accordion title="Contact Manager" icon="address-book">
    Extract and store contact details as memories from emails and messages
  </Accordion>
  <Accordion title="Analytics Dashboard" icon="chart-line">
    Read conversations and memories to generate insights and visualizations about user patterns
  </Accordion>
</AccordionGroup>

---

## Testing & Troubleshooting

<Steps>
  <Step title="Use Development Keys">
    Create a separate API key for testing to avoid affecting production data
  </Step>
  <Step title="Mark Test Content">
    Clearly mark test conversations (e.g., prefix with "[TEST]") so they're easy to identify and clean up
  </Step>
  <Step title="Verify in the Omi App">
    After creating content, open the Omi app to verify it appears correctly
  </Step>
  <Step title="Check Structured Data">
    For conversations, verify that title, overview, and action items are extracted correctly
  </Step>
</Steps>

**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](/api-reference/introduction) for the full endpoint list.

---

## Related

<CardGroup cols={2}>
  <Card title="Developer API" icon="code" href="/doc/developer/api">
    Access your own personal Omi data programmatically
  </Card>
  <Card title="Integration Apps" icon="plug" href="/doc/developer/apps/Integrations">
    Learn about building integration apps with triggers
  </Card>
  <Card title="Submit Your App" icon="paper-plane" href="/doc/developer/apps/Submitting">
    Guidelines for submitting your app to the Omi store
  </Card>
  <Card title="Chat Tools" icon="wrench" href="/doc/developer/apps/ChatTools">
    Add custom tools to Omi's AI chat
  </Card>
</CardGroup>

FilesExpand file tree

Import.mdx

Latest commit

History

Import.mdx

File metadata and controls

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