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 additiveprocessing_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
Query Parameters
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.
- cURL
- Python
- JavaScript
Response (without transcript)
Response (without transcript)
Response (with transcript)
Response (with transcript)
Response Fields
Response Fields
Transcript Segment Fields
Transcript Segment Fields
Geolocation Object Fields
Geolocation Object Fields
Structured Object Fields
Structured Object Fields
Create Conversation from Text
POST /v1/dev/user/conversations
Create a new conversation from text with full AI processing
Request Body
Request Body
- cURL
- Python
- JavaScript
Response Example
Response Example
Processing Pipeline
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
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
Request Body
Transcript Segment Fields
Transcript Segment Fields
Available Sources
Available Sources
omi, friend, openglass, phone, desktop, apple_watch, bee, plaud, frame, screenpipe, workflow, sdcard, external_integration- cURL
- Python
- JavaScript
Response Example
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
Path Parameters
Query Parameters
Query Parameters
- cURL
- Python
- JavaScript
Response Example
Response Example
Update Conversation
PATCH /v1/dev/user/conversations/{conversation_id}
Update a conversation’s title or discard status
Path Parameters
Path Parameters
Request Body
Request Body
At least one field must be provided.
- cURL
- Python
- JavaScript
Response Example
Response Example
Delete Conversation
DELETE /v1/dev/user/conversations/{conversation_id}
Delete a conversation permanently
Path Parameters
Path Parameters
- cURL
- Python
- JavaScript
Response Example
Response Example
Use Case: Upload Meeting Transcript
- Python
- JavaScript
Use Case: Export Conversations
- Bash
- Python
- JavaScript
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..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.