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

# Quick Start

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

<CardGroup cols={4}>
  <Card title="Memories" icon="brain" color="#a855f7" href="/doc/developer/api/memories">
    Read & write user memories
  </Card>

  <Card title="Conversations" icon="comments" color="#3b82f6" href="/doc/developer/api/conversations">
    Access full transcripts
  </Card>

  <Card title="Folders" icon="folder" color="#10b981" href="/doc/developer/api/folders">
    List conversation folders
  </Card>

  <Card title="Action Items" icon="list-check" color="#22c55e" href="/doc/developer/api/action-items">
    Manage tasks & to-dos
  </Card>

  <Card title="API Keys" icon="key" color="#f59e0b" href="/doc/developer/api/keys">
    Manage API access
  </Card>
</CardGroup>

***

## Quick Start

<Steps>
  <Step title="Get Your API Key" icon="key">
    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>
  </Step>

  <Step title="Make Your First Request" icon="terminal">
    <Tabs>
      <Tab title="cURL">
        ```bash theme={null}
        curl -H "Authorization: Bearer omi_dev_your_key_here" \
          https://api.omi.me/v1/dev/user/memories?limit=5
        ```
      </Tab>

      <Tab title="Python">
        ```python theme={null}
        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 theme={null}
        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>
  </Step>

  <Step title="Explore the Endpoints" icon="rocket">
    Check out the endpoint pages for detailed documentation on each resource.
  </Step>
</Steps>

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

***

## Base URL

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

<Note>
  For self-hosted instances, replace with your backend URL.
</Note>

***

## Endpoints at a Glance

<AccordionGroup>
  <Accordion title="Memories" icon="brain" defaultOpen={true}>
    | Method | Endpoint | Description |
    | - | - | - |
    | <code style={{color: '#22c55e'}}>GET</code> | `/v1/dev/user/memories` | Retrieve memories |
    | <code style={{color: '#3b82f6'}}>POST</code> | `/v1/dev/user/memories` | Create a memory |
    | <code style={{color: '#3b82f6'}}>POST</code> | `/v1/dev/user/memories/batch` | Create up to 25 memories |
  </Accordion>

  <Accordion title="Action Items" icon="list-check">
    | Method | Endpoint | Description |
    | - | - | - |
    | <code style={{color: '#22c55e'}}>GET</code> | `/v1/dev/user/action-items` | Retrieve action items |
    | <code style={{color: '#3b82f6'}}>POST</code> | `/v1/dev/user/action-items` | Create an action item |
    | <code style={{color: '#3b82f6'}}>POST</code> | `/v1/dev/user/action-items/batch` | Create up to 50 action items |
  </Accordion>

  <Accordion title="Conversations" icon="comments">
    | Method | Endpoint | Description |
    | - | - | - |
    | <code style={{color: '#22c55e'}}>GET</code> | `/v1/dev/user/conversations` | Retrieve conversations |
    | <code style={{color: '#3b82f6'}}>POST</code> | `/v1/dev/user/conversations` | Create from text |
    | <code style={{color: '#3b82f6'}}>POST</code> | `/v1/dev/user/conversations/from-segments` | Create from transcript segments |
  </Accordion>

  <Accordion title="Folders" icon="folder">
    | Method | Endpoint | Description |
    | - | - | - |
    | <code style={{color: '#22c55e'}}>GET</code> | `/v1/dev/user/folders` | List all folders |
  </Accordion>

  <Accordion title="API Keys" icon="key">
    | Method | Endpoint | Description |
    | - | - | - |
    | <code style={{color: '#22c55e'}}>GET</code> | `/v1/dev/keys` | List all API keys |
    | <code style={{color: '#3b82f6'}}>POST</code> | `/v1/dev/keys` | Create new API key |
    | <code style={{color: '#ef4444'}}>DELETE</code> | `/v1/dev/keys/{key_id}` | Revoke API key |
  </Accordion>
</AccordionGroup>

***

## Authentication

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

```http theme={null}
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](/doc/developer/api/keys).

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

***

## 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 theme={null}
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

<AccordionGroup>
  <Accordion title="HTTP Status Codes" icon="circle-exclamation" defaultOpen={true}>
    | 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 |
  </Accordion>

  <Accordion title="Error Response Format" icon="code">
    ```json theme={null}
    {
      "detail": {
        "code": "developer_memory_access_not_ready",
        "message": "Developer Memory API access is not enabled for this account."
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Security Best Practices

<CardGroup cols={2}>
  <Card title="Store Keys Securely" icon="lock" color="#22c55e">
    Use environment variables or secret management services
  </Card>

  <Card title="Rotate Keys Regularly" icon="rotate" color="#3b82f6">
    Generate new keys and revoke old ones periodically
  </Card>

  <Card title="Use Specific Keys" icon="key" color="#f59e0b">
    Create separate keys for different applications
  </Card>

  <Card title="Monitor Usage" icon="chart-line" color="#a855f7">
    Check the "last used" timestamp in your key list
  </Card>
</CardGroup>

<Tip>
  If a key is compromised, revoke it immediately from **Settings → Developer** in the Omi app.
</Tip>

***

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

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

<CardGroup cols={2}>
  <Card title="Use Developer API when you need" icon="code" color="#3b82f6">
    * Programmatic access for custom applications
    * Batch operations (multiple memories/action items)
    * Integration with external services
    * Custom automation workflows
  </Card>

  <Card title="Use MCP when you want" icon="robot" color="#a855f7">
    * AI assistants like Claude to interact with your data
    * Natural language queries and AI-powered insights
    * Context-aware AI assistance
  </Card>
</CardGroup>

<Info>
  Learn more about the Model Context Protocol in the [MCP documentation](/doc/developer/mcp/introduction).
</Info>

***

## Other APIs

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

<CardGroup cols={2}>
  <Card title="Integration Import APIs" icon="file-import" href="/doc/developer/apps/Import">
    **For App Developers** - Create conversations and memories on behalf of users who have enabled your app
  </Card>

  <Card title="Webhook Triggers" icon="bell" href="/doc/developer/apps/Integrations">
    **For App Developers** - Receive real-time notifications when memories are created or transcripts are processed
  </Card>

  <Card title="Chat Tools" icon="wrench" href="/doc/developer/apps/ChatTools">
    **For App Developers** - Add custom tools that Omi's AI can invoke during conversations
  </Card>

  <Card title="Audio Streaming" icon="microphone" href="/doc/developer/apps/AudioStreaming">
    **For App Developers** - Process raw audio bytes in real-time via WebSocket
  </Card>
</CardGroup>

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.