Skip to content

overview.mdx

Latest commit

 

History

History
281 lines (237 loc) · 10.1 KB

overview.mdx

File metadata and controls

281 lines (237 loc) · 10.1 KB
Raw
title Quick Start
icon square-terminal
description Access your Omi data programmatically with the Developer API. Build custom integrations, analytics dashboards, and automation workflows using your memories, conversations, and action items.

Overview

The Omi Developer API provides programmatic access to your personal Omi data, allowing you to build custom applications and integrations. Use it to create analytics dashboards, export data to other services, build automation workflows, or contribute data back to your Omi account.

Read & write user memories Access full transcripts List conversation folders Manage tasks & to-dos Manage API access

Quick Start

While signed in, open the Omi web app and navigate to **Developer → API Keys**. Create a key and choose only the scopes your integration needs. 
<Tip>Copy the key immediately - you won't be able to see it again!</Tip>
```bash curl -H "Authorization: Bearer omi_dev_your_key_here" \ https://api.omi.me/v1/dev/user/memories?limit=5 ``` ```python import requests 
    response = requests.get(
        "https://api.omi.me/v1/dev/user/memories",
        headers={"Authorization": "Bearer omi_dev_your_key_here"},
        params={"limit": 5}
    )
    print(response.json())
    ```
  </Tab>
  <Tab title="JavaScript">
    ```javascript
    const response = await fetch(
      "https://api.omi.me/v1/dev/user/memories?limit=5",
      { headers: { Authorization: "Bearer omi_dev_your_key_here" } }
    );
    const memories = await response.json();
    console.log(memories);
    ```
  </Tab>
</Tabs>
Check out the endpoint pages for detailed documentation on each resource. Key creation is self-service. Memory endpoints additionally require server-side account readiness, so a valid key with `memories:read` can return `403` with code `developer_memory_access_not_ready`. That response does not mean the key is invalid or missing its scope; see [Memories](/doc/developer/api/memories).

Base URL

https://api.omi.me/v1/dev
For self-hosted instances, replace with your backend URL.

Endpoints at a Glance

| Method | Endpoint | Description | |--------|----------|-------------| | GET | `/v1/dev/user/memories` | Retrieve memories | | POST | `/v1/dev/user/memories` | Create a memory | | POST | `/v1/dev/user/memories/batch` | Create up to 25 memories | | Method | Endpoint | Description | |--------|----------|-------------| | GET | `/v1/dev/user/action-items` | Retrieve action items | | POST | `/v1/dev/user/action-items` | Create an action item | | POST | `/v1/dev/user/action-items/batch` | Create up to 50 action items | | Method | Endpoint | Description | |--------|----------|-------------| | GET | `/v1/dev/user/conversations` | Retrieve conversations | | POST | `/v1/dev/user/conversations` | Create from text | | POST | `/v1/dev/user/conversations/from-segments` | Create from transcript segments | | Method | Endpoint | Description | |--------|----------|-------------| | GET | `/v1/dev/user/folders` | List all folders | | Method | Endpoint | Description | |--------|----------|-------------| | GET | `/v1/dev/keys` | List all API keys | | POST | `/v1/dev/keys` | Create new API key | | DELETE | `/v1/dev/keys/{key_id}` | Revoke API key |

Authentication

All API requests require your Developer API key in the Authorization header:

Authorization: Bearer omi_dev_your_api_key_here
MCP keys (`omi_mcp_...`) only authenticate MCP clients against `/v1/mcp/sse`. They do not authenticate REST Developer API calls. For memories, conversations, folders, and action items over HTTP, create a Developer API key (`omi_dev_...`) and call endpoints under `/v1/dev/user/...` such as `/v1/dev/user/memories`. Never commit API keys to version control or share them publicly.

Rate Limits

Limit Value
Per minute 100 requests per API key
Per day 10,000 requests per user

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642694400

Error Responses

| Code | Meaning | |------|---------| | `200 OK` | Request succeeded | | `204 No Content` | Request succeeded with no response body | | `400 Bad Request` | Invalid request parameters | | `401 Unauthorized` | Invalid or missing API key | | `403 Forbidden` | Required scope, key grant, or server-side memory availability is missing | | `404 Not Found` | Resource not found | | `422 Unprocessable Entity` | Validation error | | `429 Too Many Requests` | Rate limit exceeded | | `500 Internal Server Error` | Server error | ```json { "detail": { "code": "developer_memory_access_not_ready", "message": "Developer Memory API access is not enabled for this account." } } ```

Security Best Practices

Use environment variables or secret management services Generate new keys and revoke old ones periodically Create separate keys for different applications Check the "last used" timestamp in your key list If a key is compromised, revoke it immediately from **Settings → Developer** in the Omi app.

Developer API vs MCP

Feature Developer API MCP
Purpose Direct HTTP API access AI assistant integration
Access Read & write user data Read/write with AI context
Use Case Custom apps, dashboards, automation Claude Desktop, AI agents
Authentication Bearer token Environment variable
Best For Web apps, integrations, batch operations AI-powered workflows
If you see `404 Not Found` for legacy memory paths such as `/v1/memories` or `/v2/memories`, use the Developer API path `/v1/dev/user/memories` instead. If you see `401 Unauthorized` while using an `omi_mcp_...` key, create and use an `omi_dev_...` key for REST API requests. - Programmatic access for custom applications - Batch operations (multiple memories/action items) - Integration with external services - Custom automation workflows - AI assistants like Claude to interact with your data - Natural language queries and AI-powered insights - Context-aware AI assistance Learn more about the Model Context Protocol in the [MCP documentation](/doc/developer/mcp/introduction).

Other APIs

Looking for different API capabilities? Omi offers several APIs for different use cases:

**For App Developers** - Create conversations and memories on behalf of users who have enabled your app **For App Developers** - Receive real-time notifications when memories are created or transcripts are processed **For App Developers** - Add custom tools that Omi's AI can invoke during conversations **For App Developers** - Process raw audio bytes in real-time via WebSocket The **Developer API** (this section) is for accessing your own personal data. The APIs above are for building apps that interact with other users' data (with their permission).