# MeetingBurner API Documentation

> A REST API and Server-Sent Events stream for putting agents in live meetings. No SDK required.

## Overview

MeetingBurner has a plain REST API for putting a bot or an AI agent into a live meeting as a disclosed participant, plus a Server-Sent Events stream for reading who is present and what is being said in real time. Any language that can make an HTTP request and read an SSE stream can use it.

Base URL: `https://meetingburner.com/api/v1`

## Quick Start

### 1. Get Your API Key

Sign-up is invite-only during the private beta. Ask for an invite at support@meetingburner.com, then sign up at https://meetingburner.com/signup with the invited address. An agent cannot create an account or an API key by itself today; a person makes the key in Settings → Developer. Set the key once in your environment (for example in a `.env` file you don't commit) so it isn't pasted into every command.

### 2. Join a Meeting

```bash
curl -X POST https://meetingburner.com/api/v1/bots/join \
  -H "X-API-Key: $MEETINGBURNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "roomId": "ROOM_ID",
    "botName": "My Agent",
    "capabilities": ["listen", "artifact"],
    "purpose": "Takes notes and flags open questions"
  }'
```

`ROOM_ID` is the last part of the meeting link. To start a meeting from your key instead of the dashboard, call `POST /meetings`, but first turn on **Create meetings** for that key in Settings → Developer; it is off for a new key unless you tick it. Either way, your agent joins only after you have joined the meeting yourself, signed in to the account the key belongs to.

### 3. Read What's Happening — No WebRTC Required

```bash
curl -N \
  -H "X-API-Key: $MEETINGBURNER_API_KEY" \
  "https://meetingburner.com/api/v1/meetings/ROOM_ID/stream?connectionId=YOUR_CONNECTION_ID"
```

`YOUR_CONNECTION_ID` is the `connectionId` the join returned. Plain Server-Sent Events: who is present, who joins and leaves, and the live attributed transcript. Only add a LiveKit connection if your agent publishes or consumes audio: see https://meetingburner.com/developers/livekit-agents.md

### 4. Write Into the Meeting

```bash
curl -X POST https://meetingburner.com/api/v1/bots/post-artifact \
  -H "X-API-Key: $MEETINGBURNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "YOUR_CONNECTION_ID",
    "artifactType": "action_item",
    "text": "Write the release notes",
    "assignee": "Sam"
  }'
```

Adds an item to the live meeting record, labelled as your agent's. `artifactType` is one of `decision`, `action_item`, `key_question`, `insight`, `topic_shift`, `risk_signal`, `buy_signal`; `assignee` is optional. Needs the `artifact` capability from your join.

```bash
curl -X POST https://meetingburner.com/api/v1/bots/post-chat-message \
  -H "X-API-Key: $MEETINGBURNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connectionId": "YOUR_CONNECTION_ID",
    "text": "Recap: we ship on Friday, and Sam writes the release notes."
  }'
```

Posts one message in the meeting's group chat, shown as your agent's name with yours, never as a person. Up to 10 messages a minute per account.

### 5. Leave

```bash
curl -X POST https://meetingburner.com/api/v1/bots/leave \
  -H "X-API-Key: $MEETINGBURNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "connectionId": "YOUR_CONNECTION_ID" }'
```

Disconnects your agent and settles its usage. It is billed by the minute while connected, so leave when you are done; if you leave the meeting yourself first, your agent is removed within about three minutes.

## Authentication

Every request carries an `X-API-Key` header. Your key is tied to your MeetingBurner account: a bot can join a meeting only while you, its key's owner, are in that meeting yourself, signed in. Joining before you do fails with `owner_not_present`.

```
X-API-Key: $MEETINGBURNER_API_KEY
```

## Agent API

- `POST /meetings` — set up a meeting you host and get its link back (A meeting made this way is for right now: it ends 5 minutes after it is made if nobody joins, and expiresAt is only the latest it can run. To plan a later meeting, book it with startsAt, where booking is switched on for the account; a booked meeting is held until 15 minutes after its start.); needs the `meetings:create` scope (**Create meetings** in Settings → Developer, off by default; refused with `api_key_scope_missing` until then)
- `GET /meetings` — list the meetings this key set up
- `POST /bots/join` — connect as a disclosed agent; requires a `purpose` string
- `POST /bots/join-with-code` — the same join with no API key: a single-use code the host makes for one meeting with **Invite your agent** (ten minutes, one use, billed to the host)
- `POST /bots/post-artifact` — write a decision, action item, or insight into the live meeting record
- `POST /bots/post-chat-message` — post a message in the meeting's group chat, shown as your agent and never as a person
- `POST /bots/leave` — disconnect and settle usage
- `GET /bots/connections` — list your active connections
- `GET /agents/verify` — verify an agent passport and its current standing
- `GET /account/balance` — check your token balance

## Meeting Event Stream

`GET /meetings/{roomId}/stream` is a Server-Sent Events endpoint: presence, joins and leaves, the live attributed transcript, and artifacts. It requires the `listen` capability from your `/bots/join` call.

## Webhooks

Pass a `webhookUrl` to `/bots/join` and MeetingBurner POSTs lifecycle events to it: `meeting.ended`, `bot.disconnected`, `participant.joined`, `participant.left`. The URL must be HTTPS and cannot point at a private or loopback address. These join-time deliveries are not signed: put an unguessable token in the URL path if you need authenticity.

Account webhooks, registered in Settings → Integrations, fire `meeting.completed` once the summary is written. Each delivery carries `X-MeetingBurner-Signature: sha256=<hmac-hex>`, an HMAC-SHA256 over `${timestamp}.${rawBody}` with your secret, where the timestamp is the Unix-seconds value in `X-MeetingBurner-Timestamp`. Recompute it over the raw body, compare in constant time, and reject anything older than 300 seconds.

## MCP Server

Prefer to connect an LLM instead of writing an agent yourself? The install line is on https://meetingburner.com/developers.md. It offers these tools:

- `create_meeting` — start a meeting hosted by the key’s owner and get its link
- `list_my_meetings` — the meetings this key created
- `join_meeting` — join a live meeting as a disclosed agent, with a stated purpose
- `leave_meeting` — leave the meeting and settle usage
- `who_is_here` — who is in the room now, people and agents, each marked as which
- `read_transcript` — the live transcript, each line attributed to its speaker
- `post_artifact` — write a decision, action item or note into the meeting record
- `post_chat_message` — post in the meeting chat, labelled as your agent
- `meeting_status` — whether you are connected, what you may do, and how fresh the view is
- `get_meeting_transcript` — after a meeting has ended, its transcript, page by page
- `get_meeting_summary` — after a meeting has ended, its summary, decisions and action items
- `read_briefing` — for a delegate only: the private briefing its person wrote

## Usage and Tokens

An agent's connection time is charged to the account that owns its API key, rounded up to whole minutes, and charged when the agent leaves or the meeting ends.

- **Text agent** (no `speak` capability, including every MCP agent): 1 token per minute. 10 minutes cost 10 tokens.
- **Speaking agent** (joined with `speak`): 10 tokens per minute, rounded up to whole tokens. A one-minute call costs 10 tokens, and 10 minutes cost 100 tokens.

Before an agent is let in, its owner's balance must cover at least its first minute at its rate. Check the balance with `GET /account/balance`. Plan limits and beta pricing: https://meetingburner.com/developers.md

## Rate limits

- `POST /bots/join`: 5 a minute per account.
- `POST /bots/post-artifact`: 30 a minute per account.
- `POST /bots/post-chat-message`: 10 a minute per account (the MCP `post_chat_message` tool shares this limit).
- `POST /meetings`: 2 a minute per API key, 5 a minute across all of an account's keys, and 50 per API key in any 24 hours.
- `GET /meetings`: 2 a minute per API key.
- `GET /agents/verify`: 60 a minute per caller IP address.

A refused request answers 429 with a `Retry-After` header in seconds. Wait that long, then retry.