Project operations read and manage the projects that group your sessions, notes and cards. Note operations read and write notes as Markdown, including a session's own note. Every operation also takes an optional workspaceId. See How to read this reference for the conventions.

Operation	Kind	Tool	On	Group
`projects.list`	Read	`talkbar_read`	On	`metadata`
`projects.get`	Read	`talkbar_read`	On	`content`
`projects.trash.list`	Read	`talkbar_read`	On	`content`
`projects.create`	Write	`talkbar_change`	Off	`contentChanges`
`projects.update`	Write	`talkbar_change`	Off	`contentChanges`
`projects.pin`	Write	`talkbar_change`	Off	`contentChanges`
`projects.trash`	Write	`talkbar_delete`	Off	`contentChanges`
`projects.restore`	Write	`talkbar_change`	Off	`contentChanges`
`notes.list`	Read	`talkbar_read`	On	`content`
`notes.get`	Read	`talkbar_read`	On	`content`
`notes.trash.list`	Read	`talkbar_read`	On	`content`
`notes.create`	Write	`talkbar_change`	Off	`contentChanges`
`notes.update`	Write	`talkbar_change`	Off	`contentChanges`
`notes.append`	Write	`talkbar_change`	Off	`contentChanges`
`notes.move`	Write	`talkbar_change`	Off	`contentChanges`
`notes.pin`	Write	`talkbar_change`	Off	`contentChanges`
`notes.trash`	Write	`talkbar_delete`	Off	`contentChanges`
`notes.restore`	Write	`talkbar_change`	Off	`contentChanges`

`projects.list`

Pages the projects in a workspace with session, note and document counts and the latest session start time.

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

Arguments

limit

integer

How many to return. From 1 to 100. Default 100.

offset

integer

nextOffset from the previous page. Default 0.

Returns: {items: [{projectId, name, description, sessionCount, noteCount, documentCount, lastSessionAtMs}], totalCount, nextOffset}.

{"tool": "projects.list", "args": {}}

`projects.get`

Reads one project overview with its latest sessions (up to 20) and notes (up to 10).

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

Arguments

projectIdrequired

string

A project, from projects.list.

Returns: The projects.list fields plus sessions (rows as in sessions.list) and notes ({noteId, title, snippet, updatedAt}).

A project in the Trash is not_found.

{"tool": "projects.get", "args": {"projectId": "proj_456"}}

`projects.trash.list`

Lists the projects in the Trash.

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

Arguments

limit

integer

How many to return. From 1 to 200. Default 50.

Returns: {projects: [{projectId, name, trashedAt}]}.

`projects.create`

Creates a project, within your plan's project limit.

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

Arguments

namerequired

string

The project name. Must not be empty.

description

string

A plain-text description.

kind

string

The kind of project. One of client, engagement, recurring, internal, personal, research, product, sales, hiring, education, event, support. Default client.

color

string

The project color.

Returns: The project: {projectId, name, status, kind, pinned, updatedAt}.

At your plan's project limit the call is refused with plan_limit (limit: "projects"), counted in the workspace the call acts on. plan.get shows the limit.

{"tool": "projects.create", "args": {"name": "Northwind onboarding", "kind": "client"}}

`projects.update`

Renames a project or changes its description, kind or color.

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

Arguments

projectIdrequired

string

A project, from projects.list.

name

string

The new name. Must not be empty.

description

string | null

A plain-text description; it replaces any formatted description. null clears it.

kind

string

One of client, engagement, recurring, internal, personal, research, product, sales, hiring, education, event, support.

color

string | null

The project color. null clears it.

Returns: The project, as projects.create returns it.

Give at least one field.

`projects.pin`

Pins or unpins a project.

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

Arguments

projectIdrequired

string

A project, from projects.list.

pinnedrequired

boolean

true pins, false unpins.

Returns: {projectId, pinned}.

`projects.trash`

Moves a project to the Trash. It can be restored.

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

Arguments

projectIdrequired

string

A project, from projects.list.

Returns: {projectId, trashed: true}. Trashing a project 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.

`projects.restore`

Brings a project back from the Trash, within your plan's project limit.

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

Arguments

projectIdrequired

string

A project, from projects.list.

Returns: The project, as projects.create returns it. Restoring a project that is not in the Trash changes nothing.

At the project limit it is refused with plan_limit (limit: "projects").

`notes.list`

Pages the notes in a workspace, most recently updated first, optionally limited to a project, topic, session or a title and body search.

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

Arguments

projectId

string

Only notes filed under this project.

string

Text to find in note titles and bodies.

topicId

string

Only notes assigned this topic (from topics.list).

sessionId

string

Only the notes on this session: its own note, the notes added to its page and the notes filed under it.

limit

integer

How many to return. From 1 to 100. Default 40.

cursor

string

The nextCursor from the previous page. Must not be empty.

Returns: {items, nextCursor, hasMore, totalCount}. Each item has noteId, title, snippet, pinned, createdAt, updatedAt, sessionId, sessions, topics and projects; a search adds matchSnippet.

In each row, sessionId is set only on a session's own note; sessions lists the sessions a note is filed under.

{"tool": "notes.list", "args": {"search": "onboarding", "limit": 10}}

`notes.get`

Reads one note: its title, Markdown body (in pages) and links.

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

Arguments

noteIdrequired

string

The note, from notes.list or sessions.notes.

maxChars

integer

Page size in characters. From 1,000 to 200,000. Default 20000.

offset

integer

nextOffset from the previous read. An offset past the end is refused.

Returns: {noteId, workspaceId, title, markdown, truncated, nextOffset, pinned, createdAt, updatedAt, links}. updatedAt is what notes.update takes as expectedUpdatedAt.

A note in the Trash is not_found.

{"tool": "notes.get", "args": {"noteId": "note_789"}}

`notes.trash.list`

Lists the notes in the Trash.

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

Arguments

limit

integer

How many to return. From 1 to 200. Default 50.

Returns: {notes: [{noteId, title, trashedAt}]}.

`notes.create`

Creates a note from Markdown, optionally filed under a project and sessions.

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

Arguments

title

string

The note title. May be empty, as in the app.

markdown

string

The note body, in Markdown. (The argument is markdown; body, content or text are refused.)

projectId

string

File the note under this project.

sessionIds

string[]

File the note under these sessions. A session named twice is filed once.

pinned

boolean

Pin the note.

Returns: {noteId, title, pinned, sessionId, updatedAt, projectId, sessionIds}. projectId and sessionIds say where the note is filed.

The project and sessions must exist and not be in the Trash.

{"tool": "notes.create", "args": {"title": "Follow-up plan", "markdown": "## Next steps\n- Send the proposal by Friday", "projectId": "proj_456"}}

`notes.update`

Renames a note and/or replaces its body with Markdown.

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

Arguments

noteIdrequired

string

The note, from notes.list or sessions.notes.

title

string

The new title. An empty title clears it.

markdown

string

The new body, in Markdown. Replaces the whole body.

force

boolean

Replace a body that holds content Markdown cannot represent, such as embedded cards. Without it, such a note is refused.

expectedUpdatedAt

integer

The note's updatedAt your edit started from. If the note changed since, in TalkBar or through another call, the edit is refused with conflict and nothing is written.

Returns: {noteId, title, pinned, sessionId, updatedAt}; on a session's own note, also sessionStatus (and a warning when the session was interrupted or TalkBar is not running).

Give a title, markdown or both. A title-only edit keeps the body and its embedded links.
A conflict answer carries the note's current updatedAt: read the note again, merge, and retry.
A note in the Trash is refused: restore it first.

{"tool": "notes.update", "args": {"noteId": "note_789", "markdown": "# Plan\nUpdated after the call.", "expectedUpdatedAt": 1761990000000}}

`notes.append`

Adds Markdown to the end of a note. No conflict check is needed, since it adds to what is there.

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

Arguments

noteIdrequired

string

The note, from notes.list or sessions.notes.

markdownrequired

string

The Markdown to add. Must not be empty.

Returns: As notes.update, including sessionStatus on a session's own note.

To write into a live session's note, find its noteId with sessions.notes (role: "session").

{"tool": "notes.append", "args": {"noteId": "note_789", "markdown": "- Dana will send the contract draft."}}

`notes.move`

Sets a note's project and/or the sessions it is filed under. Other links stay.

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

Arguments

noteIdrequired

string

The note, from notes.list or sessions.notes.

projectId

string | null

The project, or null to take the note out of its project.

sessionIds

string[]

The sessions to file it under. Replaces the note's current session list.

Returns: {noteId, projectId, sessionIds}: where the note is filed now.

Give projectId, sessionIds or both.

`notes.pin`

Pins or unpins a note.

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

Arguments

noteIdrequired

string

The note, from notes.list or sessions.notes.

pinnedrequired

boolean

true pins, false unpins.

Returns: {noteId, pinned}.

`notes.trash`

Moves a note to the Trash. It can be restored.

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

Arguments

noteIdrequired

string

The note, from notes.list or sessions.notes.

Returns: {noteId, trashed: true}. Trashing a note already in the Trash succeeds.

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.

`notes.restore`

Brings a note back from the Trash.

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

Arguments

noteIdrequired

string

The note, from notes.list or sessions.notes.

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

People and companies

MCP and CLI operations to list, read, create, update and archive people and companies, and to find the sessions a person spoke in.

Scheduler

MCP and CLI operations to inspect TalkBar's scheduled jobs and to cancel or retry one.

Projects and notes