DocsAPI ReferenceLaunch a bot into a meeting
POST/api/v1/bots

Provisions an isolated VM and sends a bot participant into the specified meeting. The bot joins immediately (or enters the waiting room if admission is required). Returns a MeetingResponse with a `bot_id` UUID — use this as the primary identifier for all subsequent bot operations. The bot begins transcribing audio once it enters the meeting. Recording and video capture are opt-in via `recording_enabled` and `capture_modes`. For Zoom meetings you must provide either a `zoom_obf_token` or have a stored Zoom OAuth connection.

Headers

X-API-Keystringrequired

Your workspace API key. Format: `srvk_...`

Content-Typestringrequired

Must be `application/json`.

Request Body

application/json

platformstringrequired

The meeting platform. Must be one of `google_meet`, `zoom`, or `teams`.

Example: "google_meet"

google_meetzoomteams
meeting_urlstring

Full meeting URL (e.g. `https://meet.google.com/abc-defg-hij`). Used to derive `native_meeting_id` if not provided directly. Either `meeting_url` or `native_meeting_id` is required.

Example: "https://meet.google.com/abc-defg-hij"

native_meeting_idstring

Platform-specific meeting ID. For Google Meet: `abc-defg-hij`. For Zoom: numeric meeting ID. For Teams: 10–15 digit ID. Either this or `meeting_url` is required.

Example: "abc-defg-hij"

bot_namestring

Display name the bot will use inside the meeting. Visible to all participants.

Example: "Notetaker"

languagestring

Whisper language code for transcription (e.g. `en`, `fr`, `es`, `de`). Omit for automatic language detection.

Example: "en"

taskstring

Transcription task. `transcribe` outputs in the spoken language. `translate` outputs in English regardless of source language. Default: `transcribe`.

Example: "transcribe"

transcribetranslate
transcription_tierstring

Processing priority. `realtime` delivers segments with ~1s latency. `deferred` reduces cost and delivers after the meeting. Default: `realtime`.

Example: "realtime"

realtimedeferred
recording_enabledboolean

Whether to persist the meeting recording. Defaults to the workspace setting if omitted.

Example: true

transcribe_enabledboolean

Whether to run transcription. Defaults to the workspace setting if omitted.

Example: true

capture_modesarray

What streams to capture. Options: `audio` (default), `video`. Use `["audio", "video"]` for full video recording.

Example: ["audio","video"]

recording_formatstring

Output file format for recordings. `mp4` = H.264 + AAC audio, fast-start streamable. `mp3` = audio only. `webm` = raw WebM. Default: `mp4`.

Example: "mp4"

mp4mp3webm
voice_agent_enabledboolean

Enable voice agent capabilities (TTS speak, chat messaging, screen share). Default: `true`.

Example: true

default_avatar_urlstring

Custom avatar image URL displayed on the bot's camera feed when no screen content is active. Omit to use the default Serveka logo.

Example: "https://your-domain.com/logo.png"

enable_actionsboolean

Enable live action detection — LLM analysis of transcript segments in real time. If `false`, no LLM calls are made. Default: `false`.

Example: false

prompt_version_idstring

ID of the workspace action prompt version to use for live action detection. Falls back to workspace default, then system default.

Example: "pv_abc123"

scheduled_atstring

ISO 8601 UTC datetime. If set to a future time, the bot is scheduled instead of launched immediately. Use `POST /api/v1/bots/schedule` for a dedicated scheduling workflow.

Example: "2026-05-15T14:00:00Z"

passcodestring

Meeting passcode. Required for some Microsoft Teams meetings.

Example: "12345"

zoom_obf_tokenstring

One-time Zoom OBF token for authentication. If omitted for Zoom meetings, the backend mints one from the user's stored Zoom OAuth connection.

Example: "obf_token_xyz"

zoom_connection_idinteger

ID of a specific Zoom OAuth connection to use (from `GET /api/v1/workspace/integrations/zoom/connections`). Only applies to Zoom. Ignored if `zoom_obf_token` is provided.

Example: 3

left_alone_timeout_secondsinteger

Seconds to wait after all participants leave before the bot exits. Range: 10–3600. Default: 10.

Example: 30

startup_alone_timeout_secondsinteger

Seconds the bot waits for the first participant during startup. Range: 60–7200. Default: 1200 (20 min).

Example: 600

admission_timeout_secondsinteger

Seconds the bot waits in the waiting room before giving up. Range: 30–600. Default: 300 (5 min).

Example: 300

Responses

201Bot created. Status is `requested` immediately after creation. Use webhooks or poll `GET /api/v1/bots/{bot_id}` to track status transitions.
{
  "id": 99,
  "bot_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "google_meet",
  "native_meeting_id": "abc-defg-hij",
  "constructed_meeting_url": "https://meet.google.com/abc-defg-hij",
  "status": "requested",
  "bot_container_id": null,
  "start_time": null,
  "end_time": null,
  "data": null,
  "recording_url": null,
  "ws_url": null,
  "ws_token": null,
  "created_at": "2026-05-12T10:00:00Z",
  "updated_at": "2026-05-12T10:00:00Z"
}
400Neither `meeting_url` nor `native_meeting_id` was provided, or the provided meeting ID is invalid for the platform.
401Missing or invalid API key.
403API key is not bound to a workspace.
422Validation error — invalid platform value, malformed meeting URL, or out-of-range timeout value.