Meetings API

The Meetings API covers a meeting’s whole life: plan it ahead (or import it from a calendar), send a bot into the call (or let auto-join do it), and read the transcript in real time. It is the public Vexa API — the same surface whether you use the hosted service or self-host.

Base URL & auth


Hosted	`https://api.cloud.vexa.ai`
Self-hosted	`http://localhost:18056` (the gateway; `API_GATEWAY_HOST_PORT`, default `18056`)

Every request carries your key:

-H "X-API-Key: <API_KEY>"

Platforms

Pass one of these as platform:

Platform	`platform` value
Google Meet	`google_meet`
Zoom	`zoom`
Microsoft Teams	`teams`
Jitsi Meet	`jitsi`

The bot joins like any participant — no plugins, no host configuration. For jitsi, the full meeting_url is required (like Zoom): a Jitsi room name is scoped to a deployment — MyRoom exists on meet.jit.si and on every self-hosted instance — so only the URL says which one to join. The native_meeting_id reflects that scoping: the bare room name on meet.jit.si (MyRoom), and room@host on any other deployment ([email protected]) — so same-named rooms on different deployments never collide. A password-protected room is joined by passing the optional passcode field. To make calendar sync recognize a self-hosted deployment’s links, list its hostnames in the VEXA_JITSI_HOSTS env (comma-separated). On Jitsi the transcript also carries the meeting’s chat: each chat message arrives as a segment with source: "chat" (the sender is the speaker), and speaker names come from the conference’s own dominant-speaker signal.

Meeting statuses

A meeting is one record from plan to transcript:

Phase	`status` values	Who owns it
Planned (intent)	`idle` (no time) · `scheduled` (time set)	you — freely editable
Live (bot FSM)	`requested` · `joining` · `awaiting_admission` · `needs_help` · `active` · `stopping`	the bot lifecycle
Terminal	`completed` · `failed`	—

Sending a bot to a planned meeting (yours or auto-join’s) upgrades the same record in place — its title, workspace binding, and transcript stay together. PATCH/DELETE work only while the record is still planned; once the bot lifecycle owns it they answer 409.

Plan a meeting

Create a meeting before it happens — no bot is spawned. All fields are optional: a plan can be just a title, and the link can be attached later.

string

What the meeting is about — shown in the Meetings list.

string

ISO-8601 start time. Present → status scheduled (and auto-join arms); absent → idle.

string

A Meet/Zoom/Teams link — parsed server-side into platform + native_meeting_id. Unrecognized links are rejected with 422.

string

Bind the meeting to a shared workspace — its members then see the meeting, its live feed, and the transcript.

boolean

Send the bot automatically at start time. Default true.

POST /meetings

curl -X POST "$API_BASE/meetings" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"title":"Q3 kickoff with Acme","scheduled_at":"2026-07-10T15:00:00Z",
       "meeting_url":"https://meet.google.com/abc-defg-hij","workspace_id":"ws-acme"}'

Returns 201 with the meeting record. 409 when a non-terminal meeting already exists for the same link.

Edit or delete a plan

Planned meetings are addressed by record id (a plan without a link has no platform/native path). Send only the fields you’re changing; null clears a field (scheduled_at: null flips the status back to idle, meeting_url: null detaches the link, workspace_id: null unbinds).

PATCH /meetings/{meeting_id}

curl -X PATCH "$API_BASE/meetings/12345" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"scheduled_at":"2026-07-10T16:00:00Z","auto_join":false}'

DELETE /meetings/{meeting_id}

curl -X DELETE "$API_BASE/meetings/12345" -H "X-API-Key: $API_KEY"

Both answer 404 for a record you don’t own and 409 once the bot lifecycle owns the record. The same edit/delete is also reachable by native key — PATCH/DELETE /meetings/{platform}/{native_meeting_id} — which resolves (platform, native_meeting_id) to your newest owned row and applies the same rules (404 unknown/unowned, 409 once FSM-owned). Use it when you address meetings by their join-link identity rather than the record id; DELETE answers 200 on this path (the by-record-id DELETE answers 204).

api.v1 native-id support (per route)

api.v1 is sealed as a file hash (contracts.seal.json), which pins the schema document, not the running implementation. This table states, per route, whether the (platform, native_meeting_id) keying a 0.10 client uses is served by the 0.12 core:

Route	Native-id keying in 0.12
`PATCH /meetings/{platform}/{native_meeting_id}`	Yes — resolves to your newest owned row.
`DELETE /meetings/{platform}/{native_meeting_id}`	Yes — `200` on success (by-id path is `204`).
`GET /bots/status`	Yes — body carries both `running_bots` (0.10) and `running`/`count` (0.12).
`POST /transcripts/{platform}/{native_meeting_id}/share`	Aliased to the moved `POST /meetings/{platform}/{native_meeting_id}/share` mint. The response is the capability-token share (`{id, token, mode, expires_at}`), not the 0.10 public-URL `TranscriptShareResponse` — the public-URL-share backend is not in the 0.12 core.
`GET /recordings/{recording_id}/media/{media_file_id}/download`	Aliased to the `.../raw` master byte stream (Range-capable).
`GET /bots/{platform}/{native_meeting_id}/chat`	Restored, empty — the owner boundary is real; the message list is always empty (0.12 does not persist in-meeting chat server-side; chat flows live over the WS `va:…:chat` channel).
`POST /bots/{platform}/{native_meeting_id}/chat`	Not implemented — no bot-command (send) backend in the 0.12 core.
`POST /meetings/{meeting_id}/transcribe`	Not implemented — no on-demand re-transcribe backend in the 0.12 core.

What the seal enforces now. Because the file hash pins the document and not the running implementation, CI now also runs a reverse conformance check (gate:contract-conformance): for every (path, method) api.v1 declares, the shipped gateway + meeting-api must serve it — otherwise the route must be recorded in the audited core/gateway/contracts/api.v1/KNOWN_GAPS.json ledger (with a reason + issue link), which the gate prints loudly on every run. A sealed endpoint renamed or dropped without a ledger entry fails CI. The frozen golden examples are also driven against the real responses, so a renamed response field (e.g. running_bots → running) fails too. The two Not implemented rows above and the share response-shape divergence are the current recorded gaps — a client can rely on the seal meaning “served, or explicitly listed as a gap”, not merely “the schema file didn’t change”.

Auto-join

A scheduled meeting with a link is joined automatically: a background sweep sends the bot ~60 s before scheduled_at (never more than 10 min after — a stale plan is skipped, not joined late). Opt out per meeting with auto_join: false. Failures are loud: a concurrency-cap or spawn failure stamps auto_join_error into the meeting’s data and retries after a backoff. Timing is tunable on a self-host — see Configuration.

Calendar sync

Connect a calendar’s secret ICS address and upcoming meetings import as planned records automatically (only events carrying a recognizable Meet/Zoom/Teams link; one record per event — the next occurrence of a recurring series). The URL is a secret: read-backs return it masked. auto_join here is the global default stamped onto imported meetings.

PUT /user/calendar

curl -X PUT "$API_BASE/user/calendar" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"ics_url":"https://calendar.google.com/calendar/ical/…/basic.ics","auto_join":true}'

GET /user/calendar

curl -H "X-API-Key: $API_KEY" "$API_BASE/user/calendar"

Response

{ "ics_url_set": true, "ics_url_masked": "calendar.google.com/…s.ics", "auto_join": true }

Pasting the wrong kind of URL fails at save: a calendar page (e.g. Google’s /calendar/embed) is rejected with a 422 that points at the right field — the Secret address in iCal format (on Google Workspace domains an admin policy can hide that field; see Calendar sync for the unlock). Sync feedback — connecting from the Terminal runs a sync immediately; over the API the same two edges are yours:

POST /user/calendar/sync — run the sync NOW, get the result

curl -X POST "$API_BASE/user/calendar/sync" -H "X-API-Key: $API_KEY"

Response

{ "last_sync": "2026-07-08T15:30:00+00:00", "last_error": null,
  "counts": { "created": 3, "updated": 0, "cancelled": 0 } }

GET /user/calendar/sync — the last sync's status

curl -H "X-API-Key: $API_KEY" "$API_BASE/user/calendar/sync"

last_error, when set, is a human-readable reason (wrong-URL kind, HTTP status, oversize, redirect, not-ICS content) — the same strings the Terminal panel shows. 404 on the POST means no feed is connected; 503 means the deployment has calendar sync disabled (see Configuration). Disconnect with {"ics_url": null}. See Calendar sync for where to find the secret address.

Send a bot to a meeting

string

required

google_meet · zoom · teams

string

required

The meeting id from the join URL (e.g. abc-defg-hij).

string

Display name the bot uses in the call. Defaults to Vexa.

string

ISO code (e.g. en). Omitted = auto mode: each STT window’s language is detected independently and stamped on its segments’ language field. Set = forced mode: every STT call is pinned to this code and every segment carries it. Granularity is the transcription window (a few seconds of one speaker’s audio), not word-level; in auto mode a low-confidence detection on the Zoom/Teams (mixed-audio) lane discards the window rather than guessing. Undetermined windows yield language: null. (0.10’s allowed_languages is not part of the 0.12 API.)

string

transcribe (default) or translate.

boolean

Whether this spawn should request transcription. Resolution: an explicit value wins; else the deployment env TRANSCRIBE_ENABLED; else true. Non-boolean values (other than the common string forms true/false/1/0/yes/no/on/off) are refused with 422 (transcribe_enabled must be a boolean). When the resolved value is true and no STT backend is configured, POST /bots answers 503 with a detail naming the unset keys, e.g.

no transcription backend configured — set it in Settings or environment variables TRANSCRIPTION_SERVICE_URL + TRANSCRIPTION_SERVICE_TOKEN

. Set false for capture-only (bot may still join; no STT client is constructed).

boolean

Whether this spawn should persist an audio/video recording. Same resolution pattern as transcribe_enabled against env RECORDING_ENABLED (default true at the env resolver; the service default when callers omit it follows the request/env chain). Capture-only (transcribe_enabled=false) is not the same as recorded — recording is gated separately.

POST /bots

curl -X POST "$API_BASE/bots" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"platform":"google_meet","native_meeting_id":"abc-defg-hij","bot_name":"Vexa","language":"en"}'

If a planned meeting exists for the same link, the spawn claims it: the same record moves to requested, keeping its title, scheduled_at, and workspace binding. 409 when a bot is already active on that link; 429 past your concurrency limit. With transcription requested (the default) and STT unconfigured, the spawn is refused loud — 503 naming TRANSCRIPTION_SERVICE_URL / TRANSCRIPTION_SERVICE_TOKEN. Capture-only: {"transcribe_enabled": false} (or TRANSCRIBE_ENABLED=false for the deployment). See Configuration and Troubleshooting.

Completion service provenance

The signed meeting.completed webhook includes data.meeting.service_provenance when the meeting has complete producer-owned lifecycle facts:

{
  "bot_admitted_at": "2026-07-28T10:05:00.000Z",
  "bot_departed_at": "2026-07-28T10:30:00.000Z",
  "bot_outcome": "served",
  "transcription_provider": "customer",
  "transcription_outcome": "served",
  "lifecycle_contract_version": "2026-07-28"
}

transcription_provider is frozen when that bot is created: vexa, customer, or none. bot_admitted_at and bot_departed_at are the bot-observed lifecycle transitions, not meeting wall-clock time or delayed webhook receipt time. A bot that never reached active reports bot_outcome: "never_admitted" with both timestamps absent. The block never contains an endpoint URL, hostname, token, credential, meeting title, or transcript. If a legacy or mixed-version run lacks provider ownership or producer timestamps, the block is null or absent. Consumers must treat that as unresolved provenance; do not reconstruct it from transcribe_enabled, current user settings, endpoint URLs, or meeting start/end time.

Get the transcript

GET /transcripts/{platform}/{native_meeting_id}

curl -H "X-API-Key: $API_KEY" \
  "$API_BASE/transcripts/google_meet/abc-defg-hij"

Response

{
  "segments": [
    {
      "segment_id": "sess_9c2a:spk1:12400",
      "speaker": "Jane Liu",
      "text": "Let's lock the renewal pricing by July 1.",
      "start": 12.4, "end": 15.1,
      "language": "en",
      "completed": true,
      "confidence": 0.93,
      "words": [{ "word": "Let's", "start": 12.4, "end": 12.6, "probability": 0.98 }]
    }
  ]
}

Segments stream in while the meeting runs — poll this endpoint, or subscribe over WebSocket for live, per-segment updates. Live drafts arrive as completed: false and are replaced by completed: true confirmations.

Manage the bot

Update config — PUT /bots/{platform}/{native_meeting_id}/config

curl -X PUT "$API_BASE/bots/google_meet/abc-defg-hij/config" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"language":"es","task":"translate"}'

Stop / leave — DELETE /bots/{platform}/{native_meeting_id}

curl -X DELETE "$API_BASE/bots/google_meet/abc-defg-hij" -H "X-API-Key: $API_KEY"

Running bots — GET /bots/status

curl -H "X-API-Key: $API_KEY" "$API_BASE/bots/status"

Make the bot speak — POST /bots/{platform}/{native_meeting_id}/speak

curl -X POST "$API_BASE/bots/google_meet/abc-defg-hij/speak" \
  -H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
  -d '{"text":"Thanks everyone, wrapping up."}'

Config (PUT …/config, change language/task mid-call) and speak (POST …/speak, TTS into the call) ride the live bot-control plane and are not yet wired in the v0.12 open-core stack — they currently return 404. Send-a-bot, stop, running bots (GET /bots/status), list, and transcripts are live.

List meetings — GET /meetings

curl -H "X-API-Key: $API_KEY" "$API_BASE/meetings"

Single meeting — GET /meetings/{meeting_id}

curl -H "X-API-Key: $API_KEY" "$API_BASE/meetings/12345"

List rows are slim; detail is full

The two list endpoints — GET /bots and GET /meetings — return lightweight rows. Each row keeps its light metadata (id, status, times, title, connected docs) but omits the heavy data detail keys: speaker_events, bot_logs, recordings, status_transition, chat_messages, error_details, and last_error. Fetch a meeting’s full data from GET /meetings/{meeting_id} — the detail endpoint is unaffected and still returns every key. The list is also paged: with no limit, a default page size of 50 applies (pass limit/offset to page explicitly). GET /bots returns has_more: true when more rows remain past the current page.

Speaker-attributed transcripts

Each segment is diarized — attributed to a speaker (a bound display name, or a provisional label until it binds) — with word-level timestamps (words[]) and a confidence. Speaker attribution is text-level (who said what), via speaker binding / clustering / captions — not separate audio tracks. Times are seconds from session start; absolute_start_time / absolute_end_time give wall-clock. The same segments arrive live (completed: false, a pending draft) and then confirmed (completed: true) — the gateway forwards the confirmed-plus-pending bundle to subscribers as the meeting runs.

Recordings

The meeting’s audio recording is uploaded to object storage — on a self-host, your own MinIO bucket, so it never leaves your environment. This is the meeting audio, stored separately from the diarized transcript above (there is no “per-speaker audio” — speaker separation lives in the transcript as text).

List recordings — GET /recordings

curl -H "X-API-Key: $API_KEY" "$API_BASE/recordings"

Recording detail — GET /recordings/{recording_id}

curl -H "X-API-Key: $API_KEY" "$API_BASE/recordings/42"

Master metadata (finalize-on-read) — GET /recordings/{recording_id}/master?type=audio

curl -H "X-API-Key: $API_KEY" "$API_BASE/recordings/42/master?type=audio"

The master metadata returns a raw_url pointing at the byte stream GET /recordings/{recording_id}/media/{media_file_id}/raw, which the player loads. The /raw endpoint honours a Range header and returns 206 Partial Content with Content-Range and Accept-Ranges — these are preserved through the gateway, not only on a direct hit, so browser playback and seeking work.

In Vexa’s runtime terms, a bot is a browser container; the transcript it produces compiles into the workspace, where agents act on it. See Meetings.

Start here

How-to: Meetings

How-to: Agents

How-to: Meetings + agents

Core

Concepts

Architecture

API reference

Deployment & operations

Roadmap

Governance

Meetings API

Base URL & auth

Platforms

Meeting statuses

Plan a meeting

Edit or delete a plan

api.v1 native-id support (per route)

Auto-join

Calendar sync

Send a bot to a meeting

Completion service provenance

Get the transcript

Manage the bot

List rows are slim; detail is full

Speaker-attributed transcripts

Recordings

​Base URL & auth

​Platforms

​Meeting statuses

​Plan a meeting

​Edit or delete a plan

​api.v1 native-id support (per route)

​Auto-join

​Calendar sync

​Send a bot to a meeting

​Completion service provenance

​Get the transcript

​Manage the bot

​List rows are slim; detail is full

​Speaker-attributed transcripts

​Recordings

Base URL & auth

Platforms

Meeting statuses

Plan a meeting

Edit or delete a plan

api.v1 native-id support (per route)

Auto-join

Calendar sync

Send a bot to a meeting

Completion service provenance

Get the transcript

Manage the bot

List rows are slim; detail is full

Speaker-attributed transcripts

Recordings