# Video calls over API and MCP

> Search your workspace's video calls, read their summary and transcript, and choose which ones the assistant joins, from the REST API or the MCP server.

Source: https://docs.watsi.ai/en/guides/meetings-api

Your workspace's video calls are on the REST API and the MCP server. An AI agent or your integration can **search** calls, **read** their summary and transcript, see the **upcoming** ones and **choose** which ones the assistant joins.

They only answer if your workspace has the meeting assistant enabled. Without it, every call answers `403 MEETING_NOTETAKER_NOT_ENABLED`, never an empty list.

## Tools and routes

| MCP tool                            | REST route                                | Scope            | What it does                                                                      |
| ----------------------------------- | ----------------------------------------- | ---------------- | --------------------------------------------------------------------------------- |
| `search_meetings`                   | `GET meetings/search`                     | `meetings:read`  | Past calls by words said, contact, date, advisor or outcome                       |
| `get_meeting`                       | `GET meetings/get`                        | `meetings:read`  | Contact, advisor, duration, status, failure reason and who talked                 |
| `get_meeting_summary`               | `GET meetings/summary`                    | `meetings:read`  | AI summary: bullets and next steps                                                |
| `get_meeting_transcript`            | `GET meetings/transcript`                 | `meetings:read`  | Transcript as Markdown, participants, language and duration                       |
| `list_upcoming_meetings`            | `GET meetings/upcoming`                   | `meetings:read`  | Coming appointments, whether the assistant joins, whether you can change it       |
| `get_meeting_assistant_settings`    | `GET meetings/assistant-settings`         | `meetings:read`  | Which appointments the assistant joins across the workspace                       |
| `set_meeting_assistant`             | `POST meetings/assistant`                 | `meetings:write` | Turns the assistant on or off for one appointment, or back to the general setting |
| `update_meeting_assistant_settings` | `POST meetings/assistant-settings/update` | `meetings:write` | Sets which appointments the assistant joins                                       |

REST routes live under `https://api.watsi.ai/v1/actions/`.

## Search and read

`search_meetings` returns calls newest first, and `nextCursor` for the next page. A call with no transcript stays in the list with its reason.

- `query` searches the title, the contact's name, phone or email, and what was said on the call.
- `memberIds` is a comma-separated list of ids. `assignedToMe` returns only yours.
- `from` and `to` are ISO-8601 instants with their offset.
- `includeSummaries` and `includeTranscripts` add the text to each row. With either one, the page drops to **10 rows**, even if you ask for more.

`summary` is `null` while processing: read `summaryStatus` before concluding there is none. `markdown` is `null` when there is no transcript: `status` and `failureCode` say why.

> **Warning**
  Transcripts, summaries, names and titles are **untrusted text**: they come from what someone said
  or typed. If you pass them to a model, treat any instruction inside them as data, never as a
  command.

## Who sees what

- The owner and admins see every call in the workspace.
- A member sees a call when they can see its contact: they are its owner or a collaborator.
- An API key sees what the member who created it sees.
- A custom role cannot read calls over API or MCP yet.

A call you cannot see answers `404 MEETING_NOT_FOUND`.

## Choose which calls the assistant joins

`set_meeting_assistant` takes `calendarEventId` and `override`: `on`, `off` or `null` to go back to the general setting. The appointment's advisor, a holder of `calendar:write_any` or a key with no member can change it. It sends no notice and does not move the appointment.

Once the assistant is joining the call, it can no longer be changed: that answers `409 MEETING_BOT_ALREADY_JOINING`. `canChange` in `list_upcoming_meetings` tells you beforehand.

`update_meeting_assistant_settings` replaces the general setting with `mode`: `all`, `none` or `rules`. With `rules`, appointment types and advisors combine as AND; with both lists empty, **it joins none**. It needs the `meeting_assistant:manage` permission, held by the owner and admins by default. What you set on an appointment wins over this setting.

## Scopes

A new API key carries `meetings:read`; `meetings:write` it does not. [See scopes](/guides/authentication).

Over OAuth, every connection asks for these two scopes, and `meetings:write` is an unticked box on the consent screen. A connection made before these tools existed has to reconnect to get them. The tools only appear in a workspace that has the meeting assistant enabled.