Quick Start

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.

Memories

Read & write user memories

Conversations

Access full transcripts

Folders

List conversation folders

Action Items

Manage tasks & to-dos

API Keys

Manage API access

Quick Start

Get Your API Key

While signed in, open the Developers page in the Omi web app (app.omi.me/developers). Create a key and choose only the scopes your integration needs.

Connecting an agent rather than writing code yourself? Choose Create API Key & Prompt, then Send to My Agent Securely: the agent receives a one-time encrypted link instead of the key. See Hand a key to an agent. Otherwise copy the key immediately — you won’t be able to see it again.

Make Your First Request

cURL
Python
JavaScript

curl -H "Authorization: Bearer omi_dev_your_key_here" \
  https://api.omi.me/v1/dev/user/memories?limit=5

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())

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);

Explore the Endpoints

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.

Base URL

https://api.omi.me/v1/dev

For self-hosted instances, replace with your backend URL.

Endpoints at a Glance

Memories

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

Action Items

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

Conversations

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

Folders

Method	Endpoint	Description
`GET`	`/v1/dev/user/folders`	List all folders

API Keys

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

Resource endpoints under /v1/dev/user/... and credential introspection at /v1/dev/key require a Developer API key in the Authorization header:

Authorization: Bearer omi_dev_your_api_key_here

Key management (GET/POST /v1/dev/keys and DELETE /v1/dev/keys/{key_id}) instead requires a signed-in Firebase ID token. A developer key cannot manage other keys. See API Keys.

MCP keys (omi_mcp_...) only authenticate MCP clients against /v1/mcp. 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.

List freshness

Conversation, memory, and action-item list responses may be reused for up to 10 seconds for the same credential and query. After any write (including edits or deletion in another app), a list may reflect the previous state for up to 10 seconds. Authentication, permission checks, and rate limits apply to every poll. A 200 response with X-Omi-List-Truncated: true contains incomplete results. Do not interpret an empty or short truncated page as the end of your data. See the conversation pagination guidance below.

Rate Limits

Budgets are operation-specific, per credential context (user/app/key), rather than a blanket per-minute or daily allowance. Default budgets are:

Operation	Requests per hour
Calling key metadata	120
Memory reads	120
Action item reads / writes (separate buckets)	120 each
Goal reads / writes (separate buckets)	120 each
Conversation reads, shared across list/detail/transcript	60
Conversation list / detail (additional separate buckets)	60 each
Transcript fetch (additional bucket)	25
Conversation writes, shared	25
Conversation from-segments (additional bucket)	30
Ask	25
Memory writes	120
Memory batch writes	15

Single-memory creation also has a 30 requests/minute burst limit. Overlapping budgets all apply; for example, transcript fetches consume the shared conversation-read, detail-read, and transcript buckets. Deployment configuration may adjust effective limits. Each fixed window begins with its first counted request and resets when the bucket expires, rather than on a clock-hour boundary. Denied requests do not extend the window. There is no general 10,000/day developer quota. Quota headers are sent on rate-limit denials; do not expect them on every successful response or expect an X-RateLimit-Reset timestamp. Use Retry-After (seconds until the denied bucket resets):

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 1800

{"detail": "Rate limit exceeded. Try again in 1800s."}

Wait at least the indicated time before retrying. Retry writes only when you know they were rejected before execution; avoid repeating ambiguous writes after transport failures.

Error Responses

HTTP Status Codes

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

Error Response Format

{
  "detail": {
    "code": "developer_memory_access_not_ready",
    "message": "Developer Memory API access is not enabled for this account."
  }
}

Security Best Practices

Store Keys Securely

Use environment variables or secret management services

Rotate Keys Regularly

Generate new keys and revoke old ones periodically

Use Specific Keys

Create separate keys for different applications

Monitor Usage

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.

Use Developer API when you need

Programmatic access for custom applications
Batch operations (multiple memories/action items)
Integration with external services
Custom automation workflows

Use MCP when you want

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.

Other APIs

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

Integration Import APIs

For App Developers - Create conversations and memories on behalf of users who have enabled your app

Webhook Triggers

For App Developers - Receive real-time notifications when memories are created or transcripts are processed

Chat Tools

For App Developers - Add custom tools that Omi’s AI can invoke during conversations

Audio Streaming

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

Additional read surfaces

The Developer API shares these reads with hosted MCP:

Endpoint	Required explicit scope	Response
`GET /v1/dev/user/people`	`people:read`	`{people: [...]}`
`GET /v1/dev/user/profile`	`profile:read`	Stored AI profile, or `profile: null` with a message
`GET /v1/dev/user/screen-activity`	`screen_activity:read`	`{screen_activity: [...], next_cursor?}`

These scopes must be selected when creating a key; existing read-only keys do not acquire them automatically. Screen activity accepts UTC dates (start_date, end_date, YYYY-MM-DD, both inclusive with the entire end day), app, limit (1–1000), and cursor. Repeat identical filters with next_cursor to continue. People and profile accept no query parameters. Unknown parameters return 400. Daily summaries are available at /v1/dev/user/daily-summaries with conversations:read. Audio download is not exposed by either surface.

​Overview

Memories

Conversations

Folders

Action Items

API Keys

​Quick Start

​Base URL

​Endpoints at a Glance

​Authentication

​List freshness

​Rate Limits

​Error Responses

​Security Best Practices

Store Keys Securely

Rotate Keys Regularly

Use Specific Keys

Monitor Usage

​Developer API vs MCP

Use Developer API when you need

Use MCP when you want

​Other APIs

Integration Import APIs

Webhook Triggers

Chat Tools

Audio Streaming

​Additional read surfaces

Overview

Quick Start

Base URL

Endpoints at a Glance

Authentication

List freshness

Rate Limits

Error Responses

Security Best Practices

Developer API vs MCP

Other APIs

Additional read surfaces