> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.meetstream.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.meetstream.ai/_mcp/server.

# MeetStream — Deduplication Key & Idempotency Key Guide

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

| Mechanism | Where you send it | Best for |
|---|---|---|
| **`Idempotency-Key`** | HTTP header | Retrying the same HTTP request after network errors or timeouts |
| **`deduplication_key`** | JSON request body | Binding one bot per logical meeting/event in your own system (Recall.ai-style) |

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

| | `Idempotency-Key` (header) | `deduplication_key` (body) |
|---|---|---|
| **Scoped to** | `(your account, key)` | `(your account, key)` |
| **First call** | `HTTP 201` — bot created | `HTTP 201` — bot created |
| **Replay** | `HTTP 507` — treat as success | `HTTP 200` — looks like a normal create |
| **Key lifetime** | Bound for the life of the bot record | Bound for the life of the bot record |
| **Request body on replay** | Ignored | Ignored (except `meeting_link` is checked) |
| **Wrong meeting on replay** | Returns the original bot silently | `HTTP 409` with an explicit error |
| **Typical key source** | Fresh UUID per HTTP attempt | Your own ID (calendar event ID, CRM record, etc.) |

**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](./MeetStream_Idempotency_Key_Guide.md).

---

## `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

```bash
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`):

```json
{
  "bot_id": "bot_a1b2c3d4...",
  "transcript_id": "t_111...",
  "meeting_url": "https://meet.google.com/abc-defg-hij",
  "status": "Active"
}
```

### Example — replay with the same key and meeting

```bash
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`):

```json
{
  "bot_id": "bot_a1b2c3d4...",
  "transcript_id": null,
  "meeting_url": "https://meet.google.com/abc-defg-hij",
  "status": "Active"
}
```

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`:

```json
{
  "error": "deduplication_key already bound to a different meeting",
  "existing_bot_id": "bot_a1b2c3d4...",
  "existing_meeting_url": "https://meet.google.com/abc-defg-hij"
}
```

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

### Field rules

| Rule | Value |
|---|---|
| Required | No |
| Type | `string` |
| Length | 1–2000 characters |
| Characters | ASCII printable only (`0x20`–`0x7E`) |
| Scope | Per MeetStream account (API key owner) |

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`:

```json
{
  "bot_config": {
    "deduplication_key": "google-cal-event-abc123",
    "bot_name": "MeetStream"
  }
}
```

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

```bash
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:

```json
{
  "meeting_link": "https://meet.google.com/abc-defg-hij",
  "deduplication_key": "crm-opportunity-88421"
}
```

```http
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?

| Scenario | Recommendation |
|---|---|
| HTTP client retry after timeout / 5xx | `Idempotency-Key` |
| Queue worker redelivery (SQS, Kafka, etc.) | `Idempotency-Key` (persist key with the job) |
| "One bot per calendar event" | `deduplication_key` set to your event ID |
| "One bot per CRM record" | `deduplication_key` set to your record ID |
| Migrating from Recall.ai | `deduplication_key` (same semantics) |
| Maximum safety | Both — business ID in body, UUID in header |

---

## 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](./MeetStream_Idempotency_Key_Guide.md) — full `Idempotency-Key` reference with code samples
- [Create Bot Payload Reference](./MeetStream_Create_Bot_Payload_Reference.md) — all body fields for create-bot
- [Calendar Integration Guide](/guides/app-integrations/using-credentials-with-meetstream-api) — scheduling bots from calendar events
- API reference: https://docs.meetstream.ai/api-reference/api-reference/bot-endpoints/create-agent