Quickstart

Name: Serveka
Author: Serveka

This guide walks you through the three core steps of the Serveka platform:

Send a bot into a meeting — one API call to launch
Stream the live transcript — subscribe to real-time events via SSE
Fetch the full transcript — retrieve structured data after the meeting ends

Prerequisites

Before you begin, you need:

A Serveka account at app.serveka.com
An API key from your workspace dashboard under Settings → API Keys. Keys start with srvk_.
A meeting URL — a Google Meet, Zoom, or Microsoft Teams link that is active (or will be active soon)

All requests use the header X-API-Key: srvk_your_key_here.

Step 1: Launch a bot

Send a POST request to /api/v1/bots with the meeting URL and platform.

bash

curl -X POST https://api.serveka.com/api/v1/bots \
  -H "X-API-Key: srvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "google_meet",
    "meeting_url": "https://meet.google.com/abc-defg-hij",
    "bot_name": "Notetaker",
    "language": "en",
    "recording_enabled": true
  }'

What happens next:

Serveka provisions an isolated VM and navigates to the meeting URL.
The bot joins the meeting (or waits in the waiting room if admission is required).
Status transitions: requested → joining → awaiting_admission → active.

Response 201:

json

{
  "id": 99,
  "bot_id": "550e8400-e29b-41d4-a716-446655440000",
  "platform": "google_meet",
  "native_meeting_id": "abc-defg-hij",
  "status": "requested",
  "recording_url": null,
  "ws_url": null,
  "ws_token": null,
  "created_at": "2026-05-12T10:00:00Z",
  "updated_at": "2026-05-12T10:00:00Z"
}

Save the bot_id UUID. This is the primary identifier for all subsequent operations — polling status, subscribing to the live stream, fetching the transcript, stopping the bot.

Once the bot is active, subscribe to receive real-time transcript segments, status updates, and participant events.

Step 2a: Get the stream URL and token

bash

curl -X POST https://api.serveka.com/api/v1/bots/550e8400-e29b-41d4-a716-446655440000/subscribe \
  -H "X-API-Key: srvk_your_key_here"

Response 200:

json

{
  "url": "https://stream.serveka.com/sse/550e8400-e29b-41d4-a716-446655440000",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Step 2b: Connect to the SSE stream

Open the EventSource connection using the returned url and token:

javascript

const eventSource = new EventSource(url, {
  headers: { Authorization: `Bearer ${token}` }
});
 
// Real-time transcript segments
eventSource.addEventListener('transcript_segment', (e) => {
  const segment = JSON.parse(e.data);
  console.log(`[${segment.speaker}]: ${segment.text}`);
});
 
// Bot status changes
eventSource.addEventListener('bot_status', (e) => {
  const event = JSON.parse(e.data);
  console.log(`Bot status: ${event.status}`);
});
 
// Participant joins/leaves
eventSource.addEventListener('participant_update', (e) => {
  const event = JSON.parse(e.data);
  console.log('Participants:', event.participants);
});

SSE event stream example:

event: bot_status
data: {"status": "active", "timestamp": "2026-05-12T10:05:00Z"}

event: transcript_segment
data: {"speaker": "Alice", "text": "Let's get started with the Q3 review.", "timestamp": 1.23, "is_final": true}

event: participant_update
data: {"participants": ["Alice", "Bob", "Charlie"]}

event: transcript_segment
data: {"speaker": "Bob", "text": "Sounds good. I'll start with the numbers.", "timestamp": 8.54, "is_final": true}

All SSE event types:

Event	Payload	When
`transcript_segment`	`{ speaker, text, timestamp, is_final }`	Each transcription chunk
`bot_status`	`{ status, timestamp }`	Every status transition
`participant_update`	`{ participants: string[] }`	Someone joins or leaves
`action_detected`	`{ action_type, data }`	LLM action fired (if enabled)
`recording_ready`	`{ recording_url }`	Recording upload complete

Tip: The POST /subscribe endpoint waits up to 30 seconds for the bot VM to register. If the bot is still in joining or awaiting_admission, retry after a few seconds.

Step 3: Fetch the full transcript

After the meeting ends (bot status = completed), retrieve the full structured transcript:

bash

curl https://api.serveka.com/api/v1/bots/550e8400-e29b-41d4-a716-446655440000/transcription \
  -H "X-API-Key: srvk_your_key_here"

Response 200:

json

{
  "id": 99,
  "platform": "google_meet",
  "native_meeting_id": "abc-defg-hij",
  "constructed_meeting_url": "https://meet.google.com/abc-defg-hij",
  "status": "completed",
  "start_time": "2026-05-12T10:05:00Z",
  "end_time": "2026-05-12T11:00:00Z",
  "recordings": [],
  "notes": null,
  "segments": [
    {
      "start": 1.23,
      "end": 5.67,
      "text": "Let's get started with the Q3 review.",
      "speaker": "Alice",
      "language": "en",
      "created_at": "2026-05-12T10:05:01Z",
      "completed": true,
      "absolute_start_time": "2026-05-12T10:05:01Z",
      "absolute_end_time": "2026-05-12T10:05:05Z"
    },
    {
      "start": 8.54,
      "end": 12.10,
      "text": "Sounds good. I'll share the numbers first.",
      "speaker": "Bob",
      "language": "en",
      "created_at": "2026-05-12T10:05:08Z",
      "completed": true,
      "absolute_start_time": "2026-05-12T10:05:08Z",
      "absolute_end_time": "2026-05-12T10:05:12Z"
    }
  ]
}

Each segment in segments[] includes:

start / end — offset in seconds from meeting start
absolute_start_time / absolute_end_time — wall-clock UTC timestamps
text — transcribed speech
speaker — speaker label (diarization)
language — detected language code (e.g. "en")

Step 4 (optional): Stop the bot early

If you need to remove the bot before the meeting ends:

bash

curl -X DELETE https://api.serveka.com/api/v1/bots/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: srvk_your_key_here"

Response 202:

json

{ "message": "Bot stopping" }

The stop is asynchronous. The bot leaves gracefully and the transcript is finalized.

What's next

Core Concepts — understand the full bot lifecycle, workspaces, and scheduling
API Keys — create and manage API keys
Webhooks — receive push notifications when meetings complete
API Reference — full spec for every endpoint

Quickstart

Prerequisites

Step 1: Launch a bot

Step 2: Subscribe to the live stream

Step 3: Fetch the full transcript

Step 4 (optional): Stop the bot early

What's next