Data Import APIs

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

Authorization: Bearer sk_your_api_key_here

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

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

{}

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

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

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

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

{}

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

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

---

## Read Memories API

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

### Endpoint

### 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"]
    }
  ]
}

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