Sessions

Session operations read what the session page shows (summary, transcript, timeline, figures, notes, documents and cards) and make the changes you can make there: rename, file under a project, pin, name speakers, add cards, trash and restore. Every operation also takes an optional workspaceId. See How to read this reference for the conventions.

Working with the live session

An assistant can work with the session you are recording, and what it adds shows on the recording screen right away:

1. Call sessions.recording to find it, and check stale.
2. Read with sessions.transcript using cursor: "0:" and format: "json", then keep passing the returned nextCursor. sessions.timeline gives the points written so far, and sessions.stats gives provisional speakers.
3. Add markers (markers.create), action items (action_items.create) and knowledge cards (sessions.cards.add, sessions.cards.attach), or append to the session's note (notes.append).

While recording, the transcript, timeline points and speakers are read-only for assistants (speaker edits answer session_recording). Recording itself is controlled only in the app, and the summary and AI keywords come after recording stops.

sessions.list

Pages session metadata in a workspace, newest start first, with filters for project, series, status, start time, topic and title.

Read · runs with talkbar_read · MCP switch On by default · policy group metadata

Arguments

Returns: {items, nextCursor, hasMore, totalCount}. Each item has sessionId, title, status, startedAtMs, endedAtMs, projectId, seriesId, participantCount, pinned, source and private.

• Lists sessions that are not in the Trash; use sessions.trash.list for those.
• Pass nextCursor back as cursor for the next page.

{"tool": "sessions.list", "args": {"projectId": "proj_123", "status": "complete", "limit": 20}}

sessions.get

Reads one session: its metadata, final summary text and sections, action items and decisions.

Read · runs with talkbar_read · MCP switch On by default · policy group content

Arguments

Returns: The sessions.list fields plus speakerCount, workspaceId, sessionType, createdAt, updatedAt, revision, summary ({text, sections, generatedBy}, where generatedBy names the model and provider and says whether the summary was edited), actionItems and decisions.

• participantCount counts everyone on the session, including people who never spoke; speakerCount counts those who talked.
• revision changes whenever anything on the session page changes, so an assistant can poll it cheaply and re-read only when it moves.
• While the session records: recording: true, summaryPending: true and summary: null. The summary is written after recording stops.
• Use sessions.transcript for the transcript. A session in the Trash is not_found.

{"tool": "sessions.get", "args": {"sessionId": "ses_123"}}

sessions.recording

Returns the session recording right now, or null when nothing is recording. Call it first when working with a live session, then use its sessionId.

Read · runs with talkbar_read · MCP switch On by default · policy group metadata

Arguments: none besides workspaceId.

Returns: {recording: null} or {recording: {sessionId, title, startedAtMs, elapsedMs, revision, appRunning, stale}}.

• elapsedMs is wall-clock time since the start, pauses included (only the app knows about pauses).
• appRunning says whether TalkBar is running for this data folder (null when it cannot tell). stale: true means TalkBar is not running, so the session only looks like it is recording until TalkBar next starts and marks it interrupted.
• Never guess "the newest session" for the live one: use this operation.

{"tool": "sessions.recording", "args": {}}

sessions.stats

Reads a session's figures: how long it recorded, its breaks, turns, characters, each speaker's talk time, and which model wrote its summary for every saved length. No transcript or summary text.

Read · runs with talkbar_read · MCP switch On by default · policy group metadata

Arguments

Returns: sessionId, status, sessionType, private, startedAtMs, endedAtMs, elapsedMs, recordedMs, recordingRuns, breaks, turns, transcriptChars, speakerCount, talkTimeMs, speakers and summary. Each speaker has speakerId, contactId (the linked person, else null), name, isUser, excludedFromAi, talkTimeMs and share. summary describes the selected length and model, and lists every saved length.

• speakerId is what the sessions.speakers.* writes take.
• While the session records, speakers come from the live transcript: speakerId: null, plus turns and provisional: true.

{"tool": "sessions.stats", "args": {"sessionId": "ses_123"}}

sessions.transcript

Reads a session's transcript as the session page shows it, with speaker names and times, in pages of whole turns.

Read · runs with talkbar_read · MCP switch On by default · policy group content

Arguments

Returns: sessionId, title, startedAtMs, private, truncated, excludedFromAiSpeakers, then transcript (text) or turns (json). Paged reads add totalTurns, turnOffset and nextTurnOffset; cursor reads add nextCursor instead. Json turns carry turnId, chunkId, startMs, endMs, speaker, isUser, excludedFromAi, text and translatedText.

• Pages hold whole turns. A turnOffset past the end is refused.
• turnId and chunkId are what markers.create and action_items.create take to point at a moment.
• While the session records, turns can be provisional: true and the answer carries recording: true.
• Speakers excluded from AI are marked, not hidden. Removed turns are not reported by a cursor read; when revision changes, read again in full.

{"tool": "sessions.transcript", "args": {"sessionId": "ses_123", "format": "json", "maxChars": 50000}}

sessions.timeline

Reads a session's timeline with times, as the session page shows it.

Read · runs with talkbar_read · MCP switch On by default · policy group content

Arguments

Returns: {sessionId, title, private, points: [{pointId, at, atMs, text, translatedText, edited}]}. at is mm:ss (h:mm:ss past an hour, --:-- when a point has no time).

• pointId is what markers.create and action_items.create take to point at a timeline entry.

{"tool": "sessions.timeline", "args": {"sessionId": "ses_123"}}

sessions.notes

Lists the session's own note and the notes added to it. Read one in full with notes.get.

Read · runs with talkbar_read · MCP switch On by default · policy group content

Arguments

Returns: {sessionId, private, notes: [{noteId, title, role, preview, updatedAt}]}. role is session for the session's own note and added for notes added to it; preview is the first 160 characters.

{"tool": "sessions.notes", "args": {"sessionId": "ses_123"}}

sessions.documents

Lists the documents added to a session. Read one with documents.read.

Read · runs with talkbar_read · MCP switch On by default · policy group content

Arguments

Returns: {sessionId, private, documents: [{documentId, title, fileType, status, pinned, projectId, updatedAt}]}.

sessions.live_cards

Lists the knowledge cards and earlier action items brought into a session, and the moments the conversation came back to each.

Read · runs with talkbar_read · MCP switch On by default · policy group content

Arguments

Returns: {sessionId, private, cards, broughtInActionItems, capturedActionItems}. Cards have memoryId, title, body, type, status and cameUp. cameUp is null or {count, first, last, moments: [{at, atMs, heard, matchedTerms}]}, where heard is the words heard at that moment. Action items use the action_items.get shape; brought-in items also carry statusWhenBroughtIn and cameUp.

sessions.trash.list

Lists the sessions in the Trash.

Read · runs with talkbar_read · MCP switch On by default · policy group content

Arguments

Returns: {sessions: [{sessionId, title, trashedAt}]}.

sessions.rename

Changes a session's title. Works while the session records.

Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges

Arguments

Returns: {sessionId, title} plus sessionStatus (and a warning when the session was interrupted, or is recording while TalkBar is not running).

{"tool": "sessions.rename", "args": {"sessionId": "ses_123", "title": "Q4 roadmap review"}}

sessions.move

Files a session under a project, or takes it out of its project.

Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges

Arguments

Returns: {sessionId, projectId, previousProjectId} plus sessionStatus (and a warning when the session was interrupted, or is recording while TalkBar is not running).

• The target project must exist and not be in the Trash.

{"tool": "sessions.move", "args": {"sessionId": "ses_123", "projectId": "proj_456"}}

sessions.pin

Pins or unpins a session.

Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges

Arguments

Returns: {sessionId, pinned} plus sessionStatus (and a warning when the session was interrupted, or is recording while TalkBar is not running). Reads show the state as pinned, and revision changes.

sessions.speakers.rename

Names a speaker in a session that is not recording, as the speaker menu in the app does. The speaker is linked to the person with that name, who is created if there is none.

Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges

Arguments

Returns: {sessionId, speakerId, name, contactId}.

• A person TalkBar created for this speaker alone (not yet confirmed, linked to nothing else) is renamed instead of creating another.
• When several people have the name, the call fails and lists them, so you can link one with sessions.speakers.link.
• A name another speaker in the session already has is refused: combine the two speakers in the app instead.
• A recording session is refused with session_recording; an unknown speaker is not_found. What was said and voice data are not changed.

{"tool": "sessions.speakers.rename", "args": {"sessionId": "ses_123", "speakerId": "spk_2", "name": "Dana Lee"}}

sessions.speakers.link

Links a speaker in a session that is not recording to a person already in TalkBar. The speaker takes the person's name.

Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges

Arguments

Returns: {sessionId, speakerId, name, contactId}.

• Never creates a person: an unknown or archived person is not_found.
• A recording session is refused with session_recording.

sessions.speakers.unlink

Removes a speaker's name and person link in a session that is not recording, as Remove name does in the app. The speaker goes back to Speaker 1, Speaker 2 and so on, numbered by when they first speak.

Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges

Arguments

Returns: {sessionId, speakerId, name, contactId}.

• A recording session is refused with session_recording.

sessions.cards.add

Creates a knowledge card in a session, also while it is recording. The card shows on the recording screen right away.

Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges

Arguments

Returns: The card (memoryId, title, type, status, pinned, projectId, sessionOnly, updatedAt) with sessionId and sessionStatus (and a warning when the session was interrupted, or is recording while TalkBar is not running).

• A session holds up to 24 cards; adding a 25th is refused with limit_reached.

{"tool": "sessions.cards.add", "args": {"sessionId": "ses_123", "title": "Budget capped at $40k", "type": "decision"}}

sessions.cards.attach

Brings an existing knowledge card into a session, also while it is recording.

Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges

Arguments

Returns: {memoryId, sessionId, attached: true, alreadyAttached} plus sessionStatus (and a warning when the session was interrupted, or is recording while TalkBar is not running).

• A session holds up to 24 cards (limit_reached past that). A card from another workspace is not_found.

sessions.cards.detach

Takes a knowledge card out of a session. The card itself is kept, so this runs through talkbar_change.

Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges

Arguments

Returns: {memoryId, sessionId, attached: false} plus sessionStatus (and a warning when the session was interrupted, or is recording while TalkBar is not running).

sessions.trash

Moves a finished session to the Trash. It can be restored.

Write · runs with talkbar_delete · MCP switch Off by default · policy group contentChanges

Arguments

Returns: {sessionId, trashed: true}.

• A session that is still recording is refused with session_recording.
• Trashing a session already in the Trash succeeds and keeps the first trash date.
• Runs with talkbar_delete: confirmed with you when your AI app can ask; apps that cannot ask are refused unless Allow deletes without confirmation is on.

{"tool": "sessions.trash", "args": {"sessionId": "ses_123"}}

sessions.restore

Brings a session back from the Trash.

Write · runs with talkbar_change · MCP switch Off by default · policy group contentChanges

Arguments

Returns: {sessionId, restored: true}. Restoring a session that is not in the Trash returns the same answer.

• Counts against your plan's session limit: at the limit it is refused with plan_limit (limit: "sessions"). plan.get shows the limit.

Related

• Operations reference
• Topics and markers (session keywords and markers)
• Action items
• Knowledge
• Session details in the app