Skip to main content

Endpoints

GET

Retrieve conversations

GET Single

Get one conversation

POST

Create from text

PATCH

Update conversation

DELETE

Delete conversation

POST Segments

Create from transcript

Saved transcripts awaiting processing

When funded processing is paused at an account’s allowance limit, conversation creation still preserves the submitted transcript or external text. An additive processing_deferred: true field identifies a saved conversation waiting for cloud summaries, memories, tasks, and app processing. Its completed capture status does not imply that those generated results exist. Reading or reopening the conversation preserves this waiting state. A monthly allowance reset admits new recordings while saved waiting recordings remain waiting. The user chooses whether to process that backlog in the app, after reviewing its estimated allowance use. If it cannot all fit, the newest recordings that fit are processed and the remainder stays waiting. An upgrade can start backlog processing automatically when the estimate fits the upgraded allowance. Transcript retrieval remains available throughout.

Get Conversations

GET /v1/dev/user/conversations

Retrieve your conversation transcripts (only completed, non-discarded)

Query Parameters

Prefer cursor pagination for exports and repeated page reads. Start with offset=0 and follow X-Omi-Next-Cursor until X-Omi-Has-More is false. Nonzero offsets also return X-Pagination-Guidance. If X-Omi-List-Truncated: true is present, the page is incomplete even when it is empty. Start a cursor traversal from offset zero; for transcript, folder, or starred reads, narrow the date window. Repeating a large offset cannot advance past the same budget boundary. List results may be up to 10 seconds stale after any write. Response bodies remain arrays.

Response (without transcript)


Create Conversation from Text

POST /v1/dev/user/conversations

Create a new conversation from text with full AI processing

Request Body

Response Example

Processing Pipeline

When you create a conversation, the following happens automatically:
  • Discard Detection: Determines if content is meaningful enough to save
  • Structured Generation: Creates title, overview, category, and emoji
  • Action Item Extraction: Identifies and creates action items (with deduplication against past 2 days)
  • Memory Extraction: Extracts interesting facts and insights (up to 4 per conversation)
  • App Integration: Triggers enabled summarization apps
  • Webhooks: Notifies external systems
Memories and action items are extracted asynchronously. Use the GET endpoints to retrieve them after creation.

Create Conversation from Transcript Segments

POST /v1/dev/user/conversations/from-segments

Create from structured transcript with speaker diarization
When a conversation created with a stable client session ID is deleted, retries return HTTP 200 with the same id, status: "deleted", and discarded: true, without recreating or processing content. Clients should resolve the upload and purge its local transcript rather than retrying or fetching the deleted conversation. Requests without a client session ID create a fresh random identity and cannot be linked to an earlier deleted upload. Deletion intent is retained as content-free metadata under the account and is removed by account deletion. It commits before derived-data cleanup; a failed delete remains retryable while this intent prevents backlog recreation. No automatic tombstone expiry is currently configured.

Request Body

omi, friend, openglass, phone, desktop, apple_watch, bee, plaud, frame, screenpipe, workflow, sdcard, external_integration

Response Example

Unlike text-based conversations, transcript segments ARE stored in the transcript_segments field and can be retrieved with include_transcript=true.

Get Single Conversation

GET /v1/dev/user/conversations/{conversation_id}

Retrieve a single conversation by ID

Path Parameters

Query Parameters

Response Example


Update Conversation

PATCH /v1/dev/user/conversations/{conversation_id}

Update a conversation’s title or discard status

Path Parameters

Request Body

At least one field must be provided.

Response Example

Use discarded: true to hide a conversation from the main list without permanently deleting it.

Delete Conversation

DELETE /v1/dev/user/conversations/{conversation_id}

Delete a conversation permanently

Path Parameters

Response Example

This action is permanent. Deleted conversations and their associated photos cannot be recovered. Consider using PATCH with discarded: true to hide a conversation instead.

Use Case: Upload Meeting Transcript


Use Case: Export Conversations

Public shared notes for agents

For a conversation the owner has already shared, the same public URL supports HTML, Markdown, and the public JSON payload. These representations require no login and use the existing share visibility rules; private or revoked shares return 404 for machine representations and show an unavailable page in HTML.
The .md and .json suffixes select the same representations, independent of Accept. Default requests receive HTML. Share responses vary on Accept and advertise alternate representations in HTTP Link headers; the HTML page also contains alternate links. Share discovery documents these URLs. Markdown comes from the public structured payload, including overview, sections, participants, action items, and transcript. The explicit allowlist exposes section heading, body and kind, plus action-item description, completion, owner_name, due_at and context. It excludes attendee emails, private calendar fields, insights, task IDs, confidence scores and section evidence IDs. Existing public note text is included as authored; this is not a content redaction service. Times are explicitly UTC, with ISO-8601 instants in Markdown and JSON. Transcript labels use elapsed offsets from the conversation start (HH:MM:SS). Speaker names use person links or an exact match to a public participant name; roster order cannot identify a diarized speaker. An unmatched speaker string is not a name: those turns use Speaker N when a speaker id exists, otherwise Speaker unknown. The account holder without a verified name stays Owner. Event times on the page and in Markdown use the same UTC labels. Unknown action owners and due times appear as Unknown. An email-shaped owner_name is omitted.

Pagination, search, and evidence

Lists keep their JSON array shape. limit is clamped to 1–200. Read X-Omi-Effective-Limit and X-Omi-Has-More. Offset-only modes (transcripts, folder or starred filters) return X-Omi-Next-Offset when more rows exist. Default lists return X-Omi-Next-Cursor: send it as cursor with the same filters instead of offset. Cursors require include_transcript=false and no folder_id or starred filter. Prefer cursors for a changing account. Offset sweeps are not snapshots and can overlap when new conversations arrive. These headers are exposed to browser clients. Date filters compare created_at, not recording start time. Both bounds are inclusive ISO 8601 instants; missing timezone offsets mean UTC. A date-only end on this API means midnight, whereas MCP tools include the whole UTC end day. For non-overlapping daily API windows use 00:00:00Z through 23:59:59.999999Z, then start the next day at 00:00:00Z. Reversed bounds return 400. Other unknown list query parameters are ignored and counted in X-Omi-Ignored-Query-Params. query is not a list parameter and returns 400; use the search route below. Use GET /v1/dev/user/conversations/search?query=budget&limit=10 with conversations:read. Optional start_date and end_date use the instant rules above; limit is 1–100. This returns {conversations, search_coverage, message}, using the same semantic search and keyword recovery as MCP. Unindexed content can still match even when results are empty. If semantic retrieval finds no hydrated matches and keyword retrieval is unavailable, the response is 503 with an explanation; use a date-window list to inspect the account. List and detail responses include transcript_included. A false value means transcript text was not requested. Where transcript evidence was loaded, responses also expose participants_included: true, participants (stored speaker_id, person_id, is_user mappings), and unique person_ids. Transcript-free cards report participants_included: false; an empty mapping does not prove nobody participated. Names are not inferred from summary prose.