Core Concepts

Serveka is built around a few key resources that work together. Understanding how they relate makes every API call predictable.

Bots

A bot is an AI participant that Serveka dispatches into a meeting on your behalf. Each bot runs in its own isolated VM. When the meeting ends (or you stop it), the VM is destroyed.

When you create a bot via POST /api/v1/bots, Serveka returns a bot_id — a UUID that is the primary identifier for all bot operations. The integer id field exists for internal use; always use bot_id.

Bot status lifecycle

Every bot moves through a predictable sequence of statuses:

requested → joining → awaiting_admission → active → stopping → completed
                           │                  │
                           └── failed ────────┘

completed and failed are terminal — once a bot reaches either state, it cannot transition further.

Completion reasons

When a bot reaches completed, the data.completion_reason field explains why:

Timeout defaults

Meetings

A meeting is the underlying record that a bot is attached to. One meeting corresponds to one physical meeting session (identified by its native_meeting_id — the platform-specific code like abc-defg-hij for Google Meet).

Multiple bots can be attached to the same meeting if you send multiple bots to the same URL. The /api/v1/meetings/{meeting_id}/bots endpoint lists all bots that attended a given meeting.

Meeting vs. bot

• Bot (/api/v1/bots/{bot_id}) — your handle on a specific participant. Use this for control operations (stop, speak, screen share) and live streaming.
• Meeting (/api/v1/meetings/{meeting_id}) — the logical container. Use this to query transcripts, recordings, and update metadata like name and notes after the fact.

Transcription

Transcription happens in real time during the meeting. Serveka uses Deepgram for speech-to-text processing.

Each transcription segment includes:

• start / end — relative timestamps in seconds from meeting start
• absolute_start_time / absolute_end_time — wall-clock UTC timestamps
• text — the transcribed words
• speaker — speaker label from diarization (e.g. "Speaker 1")
• language — detected language code (e.g. "en", "fr")

Transcription modes:

Recording

Recording is optional and disabled by default. Enable it with recording_enabled: true when creating a bot.

Capture modes control what is recorded:

Output formats:

After the meeting, recording files are accessible via presigned download URLs (recording_url field on the bot response, time-limited to 1 hour).

Live streaming (SSE)

Every active bot can stream real-time events to your app via Server-Sent Events (SSE).

How it works:

1. Call POST /api/v1/bots/{bot_id}/subscribe to get a stream url and short-lived JWT token
2. Open an EventSource connection to the url with the token in the Authorization header
3. Receive named SSE events as the meeting progresses

The subscription endpoint waits up to 30 seconds for the bot VM to register. If it times out, the bot may not be active yet — retry after a few seconds.

Workspaces

A workspace is an isolated environment with its own API keys, bots, recordings, members, webhooks, and billing.

Key properties:

• Every API key is scoped to exactly one workspace
• The workspace is resolved automatically from the key — you never pass workspace_id in the request body for most operations
• Members have roles: owner, admin, or member
• You can invite members by email; they get a 7-day invitation link

Role permissions:

Scheduling

Instead of launching a bot immediately, you can schedule one for a future meeting. This is useful for calendar-integrated workflows.

Use POST /api/v1/bots/schedule with a scheduled_start_at (ISO 8601 UTC) and Serveka will automatically launch the bot at the right time.

The join_offset_seconds field lets you control when the bot actually joins relative to scheduled_start_at. The default is -60 — the bot joins 60 seconds before the scheduled start time to be ready when the meeting opens.

Scheduled bots have their own statuses: scheduled → launched / cancelled / failed.

Voice agent

When voice_agent_enabled: true (the default), the bot can:

• Speak — Send it text and it speaks during the meeting using TTS (POST /api/v1/bots/{bot_id}/speak)
• Chat — Send a chat message in the meeting's chat panel (POST /api/v1/bots/{bot_id}/chat)
• Screen share — Display a URL on the bot's virtual screen (POST /api/v1/bots/{bot_id}/screen)
• Hand raise — Raise or lower a hand in the meeting (POST/DELETE /api/v1/bots/{bot_id}/hand)

API key prefix

All Serveka API keys start with srvk_. When you create a key via POST /api/v1/api-keys, the full secret is returned once — save it immediately. Subsequent reads return only metadata (key id, prefix, last_used_at, expiry) but never the secret.

Keys can have optional expiry dates. A key with expires_at set will start returning 401 after that timestamp.