Scheduling

Instead of launching a bot immediately, you can schedule one for a future meeting. This is useful for calendar-integrated workflows where you want the bot to join automatically at the meeting start time.

How scheduling works

When you create a scheduled bot, Serveka stores the configuration and automatically launches the bot at the calculated join time:

• Join time = scheduled_start_at + join_offset_seconds
• The default join_offset_seconds is -60, meaning the bot joins 60 seconds before the meeting starts to be ready when participants arrive.

Creating a scheduled bot

Use POST /api/v1/bots/schedule with the meeting details and start time:

curl -X POST https://api.serveka.com/api/v1/bots/schedule \
  -H "X-API-Key: srvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "meeting_url": "https://meet.google.com/abc-defg-hij",
    "scheduled_start_at": "2026-05-15T14:00:00Z",
    "title": "Weekly Team Standup",
    "join_offset_seconds": -120,
    "bot_name": "Notetaker",
    "language": "en",
    "recording_enabled": true,
    "transcribe_enabled": true
  }'

Required fields:

• meeting_url: The full meeting URL (platform auto-detected)
• scheduled_start_at: ISO 8601 UTC datetime for when the meeting starts (must be in the future)

Commonly used options:

• title: Display title for this scheduled slot
• join_offset_seconds: Seconds relative to scheduled_start_at when the bot joins (negative = join early, default: -60)
• bot_name: Display name for the bot in the meeting
• language: Transcription language code (e.g., en, es)
• recording_enabled: Whether to record the meeting
• transcribe_enabled: Whether to transcribe audio
• capture_modes: What streams to capture (default: ["audio"])
• recording_format: Output format for recordings (default: mp4)

Response 201:

{
  "id": 7,
  "workspace_id": "aaaaaaaa-0000-0000-0000-000000000001",
  "meeting_url": "https://meet.google.com/abc-defg-hij",
  "platform": "google_meet",
  "title": "Weekly Team Standup",
  "scheduled_start_at": "2026-05-15T14:00:00Z",
  "join_offset_seconds": -120,
  "status": "scheduled",
  "origin": "api",
  "settings": { "bot_name": "Notetaker", "language": "en", "recording_enabled": true },
  "error_message": null,
  "meeting_id": null,
  "created_at": "2026-05-12T10:00:00Z",
  "updated_at": "2026-05-12T10:00:00Z"
}

Scheduled bot statuses

Scheduled bots go through these statuses:

• scheduled - Created and waiting for launch time
• launched - Bot has been dispatched to the meeting
• cancelled - You cancelled the scheduled bot
• failed - An error occurred preventing launch

Listing scheduled bots

Get all scheduled bots in your workspace:

curl https://api.serveka.com/api/v1/bots/schedule \
  -H "X-API-Key: srvk_your_key_here"

Filter by status:

curl "https://api.serveka.com/api/v1/bots/schedule?status=scheduled" \
  -H "X-API-Key: srvk_your_key_here"

Getting a specific scheduled bot

Retrieve details for one scheduled bot by its integer ID:

curl https://api.serveka.com/api/v1/bots/schedule/7 \
  -H "X-API-Key: srvk_your_key_here"

Updating a scheduled bot

Change the time or settings for a bot that hasn't launched yet (status must be scheduled):

curl -X PATCH https://api.serveka.com/api/v1/bots/schedule/7 \
  -H "X-API-Key: srvk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_start_at": "2026-05-15T15:00:00Z",
    "recording_enabled": false
  }'

All fields are optional — only provided fields are updated.

Cancelling a scheduled bot

Prevent a scheduled bot from launching:

curl -X DELETE https://api.serveka.com/api/v1/bots/schedule/7 \
  -H "X-API-Key: srvk_your_key_here"

Response 200:

{ "message": "Scheduled bot cancelled." }

You can only cancel bots with status scheduled. Once a bot is launched, you must stop it using the regular bot stop endpoint (DELETE /api/v1/bots/{bot_id}).

What happens at launch time

At the calculated join time (scheduled_start_at + join_offset_seconds):

1. Serveka automatically creates a bot with the provided settings
2. The scheduled bot's status changes from scheduled to launched
3. The meeting_id field is populated with the internal meeting UUID
4. You can now manage the bot like any other bot using its bot_id UUID

The scheduled bot record remains in the system for historical reference even after launching.