MeetStream — Deduplication Key & Idempotency Key Guide

This guide explains the two ways to avoid duplicate bots when calling Create Bot:

Both are optional. If you omit them, every call creates a new bot.

Scope

• Idempotency-Key — POST /api/v1/bots/create_bot only
• deduplication_key — POST /api/v1/bots/create_bot and POST /calendar/schedule/{event_id}

At a glance

Rule of thumb: use Idempotency-Key for transport-level retries; use deduplication_key when your app already has a stable ID for “this meeting should have one bot.”

For a deeper dive on Idempotency-Key, see Idempotency Key Guide.

deduplication_key (request body)

Pass a string in the JSON body to say: “for this account, this key should always map to the same bot.”

Example — first create

$
curl -X POST "https://api.meetstream.ai/api/v1/bots/create_bot" \
>
  -H "Authorization: Token <YOUR_API_KEY>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "meeting_link": "https://meet.google.com/abc-defg-hij",
>
    "deduplication_key": "crm-opportunity-88421",
>
    "video_required": false
>
  }'

Response (HTTP 201):

1
{
2
  "bot_id": "bot_a1b2c3d4...",
3
  "transcript_id": "t_111...",
4
  "meeting_url": "https://meet.google.com/abc-defg-hij",
5
  "status": "Active"
6
}

Example — replay with the same key and meeting

$
curl -X POST "https://api.meetstream.ai/api/v1/bots/create_bot" \
>
  -H "Authorization: Token <YOUR_API_KEY>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "meeting_link": "https://meet.google.com/abc-defg-hij",
>
    "deduplication_key": "crm-opportunity-88421"
>
  }'

Response (HTTP 200):

1
{
2
  "bot_id": "bot_a1b2c3d4...",
3
  "transcript_id": null,
4
  "meeting_url": "https://meet.google.com/abc-defg-hij",
5
  "status": "Active"
6
}

Same bot_id as the first call. No new bot. No extra credits.

The replay response is intentionally indistinguishable from a fresh create (aside from transcript_id being null on replay, same as idempotency replays).

Example — same key, different meeting (error)

If you reuse a deduplication_key but change meeting_link, MeetStream returns HTTP 409:

1
{
2
  "error": "deduplication_key already bound to a different meeting",
3
  "existing_bot_id": "bot_a1b2c3d4...",
4
  "existing_meeting_url": "https://meet.google.com/abc-defg-hij"
5
}

This is deliberate — it surfaces a client bug instead of silently joining the wrong meeting.

Field rules

Good key choices: calendar event ID, CRM opportunity ID, internal job ID, user_id + meeting_start_time.

Avoid: timestamps that change on every click, auto-increment integers shared across workers without coordination.

Calendar scheduling

deduplication_key also works on POST /calendar/schedule/{event_id}. Put it in bot_config:

1
{
2
  "bot_config": {
3
    "deduplication_key": "google-cal-event-abc123",
4
    "bot_name": "MeetStream"
5
  }
6
}

Replay behavior matches create-bot: HTTP 200 with the existing scheduled bot, or HTTP 409 if the meeting URL does not match.

Idempotency-Key (HTTP header)

Pass a unique string in the Idempotency-Key header to safely retry the same HTTP request without creating duplicate bots.

Example

$
curl -X POST "https://api.meetstream.ai/api/v1/bots/create_bot" \
>
  -H "Authorization: Token <YOUR_API_KEY>" \
>
  -H "Content-Type: application/json" \
>
  -H "Idempotency-Key: 9b1c3f4a-7e2b-4d8f-9a1c-2e6f4b8a0c11" \
>
  -d '{
>
    "meeting_link": "https://meet.google.com/abc-defg-hij",
>
    "video_required": false
>
  }'

• First call → HTTP 201
• Retry with the same header → HTTP 507 (treat as success)

Generate one UUID per logical create attempt, persist it across retries, and accept both 201 and 507 as success.

Using both together

You may send both on the same request. MeetStream checks Idempotency-Key first, then deduplication_key.

Typical pattern:

1
{
2
  "meeting_link": "https://meet.google.com/abc-defg-hij",
3
  "deduplication_key": "crm-opportunity-88421"
4
}

1
Idempotency-Key: 9b1c3f4a-7e2b-4d8f-9a1c-2e6f4b8a0c11

• deduplication_key = stable business ID (survives across days and re-schedules)
• Idempotency-Key = per-HTTP-attempt UUID (survives network retries for that single call)

Which one should I use?

Shared guarantees and limits

Both mechanisms share these behaviors:

1. Per-account isolation — the same key value used by two different MeetStream accounts does not collide.
2. No parallel-race protection — two simultaneous first-creates with the same key may both succeed. Serialize retries in your client when possible.
3. Failed creates are not cached — if the original request failed before a bot row was written (validation error, wallet rejection, etc.), a retry executes as a fresh create.
4. Lookup fails open — on rare internal lookup errors, MeetStream proceeds with creation rather than blocking the request.
5. No key expiration — keys stay bound for the lifetime of the bot record. Generate a new key for each distinct logical create.

FAQ

Q: Does a replay charge credits? A: No. Only the original successful create charges credits.

Q: Can I look up a bot by deduplication_key or Idempotency-Key later? A: Not via a dedicated API endpoint. Use the bot_id returned in the response.

Q: What HTTP codes should my client treat as success? A:

• With Idempotency-Key only → 201 and 507
• With deduplication_key only → 201 and 200
• With both → 201, 200, and 507

Q: Does deduplication_key work for scheduled bots (join_at)? A: Yes, on POST /api/v1/bots/create_bot with a future join_at, and on calendar schedule endpoints.

Q: What if I omit both? A: Every call creates a new bot, same as before these features existed.

Related docs

• Idempotency Key Guide — full Idempotency-Key reference with code samples
• Create Bot Payload Reference — all body fields for create-bot
• Calendar Integration Guide — scheduling bots from calendar events
• API reference: https://docs.meetstream.ai/api-reference/api-reference/bot-endpoints/create-agent