> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omi.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Data Import APIs

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

<CardGroup cols={2}>
  <Card title="Create Conversation" icon="message-plus">
    Add new conversations to a user's account from external sources
  </Card>

  <Card title="Create Memories" icon="brain">
    Add facts and knowledge to the user's memory bank
  </Card>

  <Card title="Read Conversations" icon="messages">
    Access and retrieve a user's conversation history
  </Card>

  <Card title="Read Memories" icon="lightbulb">
    Access facts stored in the user's knowledge base
  </Card>
</CardGroup>

***

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

<Steps>
  <Step title="Understand Omi App Basics">
    Familiarize yourself with [Omi app development](/doc/developer/apps/Introduction) and [integration apps](/doc/developer/apps/Integrations)
  </Step>

  <Step title="Create Your App">
    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
  </Step>

  <Step title="Generate API Keys">
    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>
  </Step>

  <Step title="User Enables Your App">
    The user must explicitly enable your app in their Omi account before you can access their data
  </Step>
</Steps>

***

## Authentication

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

```
Authorization: Bearer sk_your_api_key_here
```

<Note>The API key must belong to the app specified in the URL path (`app_id`).</Note>

***

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

```json theme={null}
{
  "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):**

```json theme={null}
{}
```

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

<AccordionGroup>
  <Accordion title="Example: Phone Call Transcript" icon="phone">
    ```python theme={null}
    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"
        }
    )
    ```
  </Accordion>

  <Accordion title="Example: Text Messages" icon="comment-sms">
    ```python theme={null}
    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"
        }
    )
    ```
  </Accordion>

  <Accordion title="Example: Email" icon="envelope">
    ```python theme={null}
    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"
        }
    )
    ```
  </Accordion>

  <Accordion title="Example: Social Post with Location" icon="location-dot">
    ```python theme={null}
    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}
        }
    )
    ```
  </Accordion>
</AccordionGroup>

***

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

<Tabs>
  <Tab title="Extract from Text">
    Provide raw text and let Omi automatically extract relevant memories:

    ```json theme={null}
    {
      "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
  </Tab>

  <Tab title="Explicit Memories">
    Provide structured memory objects directly:

    ```json theme={null}
    {
      "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
  </Tab>
</Tabs>

### Response

**Success (200 OK):**

```json theme={null}
{}
```

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

<AccordionGroup>
  <Accordion title="Example: Extract from Email" icon="envelope">
    ```python theme={null}
    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"
        }
    )
    ```
  </Accordion>

  <Accordion title="Example: Explicit User Preferences" icon="sliders">
    ```python theme={null}
    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"]}
            ]
        }
    )
    ```
  </Accordion>
</AccordionGroup>

***

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

```json theme={null}
{
  "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}
    }
  ]
}
```

<Accordion title="Example: Paginated Retrieval" icon="list">
  ```python theme={null}
  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 theme={null}
{
  "memories": [
    {
      "id": "memory_id_1",
      "content": "User prefers vegetarian food options",
      "created_at": "2024-03-15T12:00:00Z",
      "tags": ["preferences", "food"]
    }
  ]
}
```

<Accordion title="Example: Retrieve All Memories" icon="brain">
  ```python theme={null}
  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                            |

***

## Future Capabilities

The Omi team is expanding the available capabilities. Coming soon:

* Update existing conversations
* Update existing memories
* Set reminders
* Access and update user preferences

***

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