# Roam HQ Developer Documentation

> Build integrations with Roam HQ, your team's virtual office.
> Post messages, retrieve transcripts, manage users, and subscribe to real-time events.

## Quick Start

Create an API client in **Roam Administration > Developer** to get your credentials.

```bash
curl -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Roam-Version: 2026-08-07" \
  https://api.ro.am/v1/token.info
```

- [Quick Start Guide](https://developer.ro.am/docs/intro.md): Create an API client and make your first request
- [Notification bot](https://developer.ro.am/docs/guides/quickstart-notification-bot.md): API key → `chat.post`
- [Interactive bot](https://developer.ro.am/docs/guides/quickstart-interactive-bot.md): Webhooks + reply loop
- [AI agent / MCP](https://developer.ro.am/docs/guides/quickstart-ai-agent.md): Claude/ChatGPT or PAT + MCP
- [API Versioning](https://developer.ro.am/docs/guides/api-versioning.md): Dated versions, `Roam-Version` header, and version history
- [Migration Guide: v0 → v1](https://developer.ro.am/docs/guides/migration-v0-to-v1.md): ID formats, renamed endpoints, webhook envelope
- [Previous Versions (Legacy)](https://developer.ro.am/docs/previous-versions.md): frozen `/v0` Chat and Webhooks surfaces

## Guides

- [Access Models](https://developer.ro.am/docs/guides/access-models.md)
- [Api Versioning](https://developer.ro.am/docs/guides/api-versioning.md)
- [Block Kit](https://developer.ro.am/docs/guides/block-kit.md)
- [Error Codes](https://developer.ro.am/docs/guides/error-codes.md)
- [Identity And Principals](https://developer.ro.am/docs/guides/identity-and-principals.md)
- [Migration V0 To V1](https://developer.ro.am/docs/guides/migration-v0-to-v1.md)
- [Oauth](https://developer.ro.am/docs/guides/oauth.md)
- [Quickstart Ai Agent](https://developer.ro.am/docs/guides/quickstart-ai-agent.md)
- [Quickstart Interactive Bot](https://developer.ro.am/docs/guides/quickstart-interactive-bot.md)
- [Quickstart Notification Bot](https://developer.ro.am/docs/guides/quickstart-notification-bot.md)
- [Responses And Errors](https://developer.ro.am/docs/guides/responses-and-errors.md)
- [Scopes](https://developer.ro.am/docs/guides/scopes.md)
- [Sdks](https://developer.ro.am/docs/guides/sdks.md)
- [Sender Profiles](https://developer.ro.am/docs/guides/sender-profiles.md)
- [Unfurling Links](https://developer.ro.am/docs/guides/unfurling-links.md)

## Pre-built Integrations

- [Github Actions](https://developer.ro.am/docs/integrations/github-actions.md)
- [Github On The Map](https://developer.ro.am/docs/integrations/github-on-the-map.md)
- [Hermes](https://developer.ro.am/docs/integrations/hermes.md)
- [Lobby Agents](https://developer.ro.am/docs/integrations/lobby-agents.md)
- [Lobby Embed](https://developer.ro.am/docs/integrations/lobby-embed.md)
- [Mcp](https://developer.ro.am/docs/integrations/mcp.md)
- [N8n](https://developer.ro.am/docs/integrations/n8n.md)
- [Openclaw](https://developer.ro.am/docs/integrations/openclaw.md)
- [Webhook Relays](https://developer.ro.am/docs/integrations/webhook-relays.md)
- [Webhook](https://developer.ro.am/docs/integrations/webhook.md)
- [Zapier](https://developer.ro.am/docs/integrations/zapier.md)

## Common Use Cases

### Build a Chat Bot
Create an OAuth app to receive messages via webhooks and respond programmatically.
- [chat.message](https://developer.ro.am/docs/webhooks/chat-message.md) - Subscribe to incoming messages (creates/edits/deletes under the v1 envelope)
- [chat.post](https://developer.ro.am/docs/api/chat-post.md) - Send responses
- [chat.typing](https://developer.ro.am/docs/api/chat-typing.md) - Show typing indicators

### Post-Meeting Automation
Get notified when meetings finish and content is ready.
- [meeting.ended](https://developer.ro.am/docs/webhooks/meeting-ended.md) - Transcript/summary ready (v1 successor of `transcript:saved`)
- [magicast.created](https://developer.ro.am/docs/webhooks/magicast-created.md) - Magicast/recording asset ready
- [meeting.transcript](https://developer.ro.am/docs/api/meeting-transcript.md) - Fetch transcript content
- [meeting.list](https://developer.ro.am/docs/api/meeting-list.md) - List meetings

### Send Notifications
Post alerts from CI/CD, monitoring, or ticketing systems into Roam groups.
- [chat.post](https://developer.ro.am/docs/api/chat-post.md) - Post messages to groups or users
- [group.list](https://developer.ro.am/docs/api/group-list.md) - Find group IDs

### Compliance & Audit
Review audit logs and meeting records (v1).
- [userauditlog.list](https://developer.ro.am/docs/api/userauditlog-list.md) - User audit log entries
- [messageevent.export](https://developer.ro.am/docs/api/messageevent-export.md) - Daily message archive export (JSON Lines)
- [meeting.list](https://developer.ro.am/docs/api/meeting-list.md) - List meetings

### On-Air Event Management
Create events, manage guest lists, and track RSVPs programmatically.
- [onair.event.create](https://developer.ro.am/docs/onair-api/onair-event-create.md) - Create events
- [onair.guest.add](https://developer.ro.am/docs/onair-api/onair-guest-add.md) - Add guests
- [onair.guest.rsvp](https://developer.ro.am/docs/webhooks/onair-guest-rsvp.md) - RSVP webhook

## Roam API (v1)

Base URL: `https://api.ro.am/v1`. Prefer this surface for new integrations. Success bodies use an `ok` envelope; send `Roam-Version` to pin the contract.

- [API Overview](https://developer.ro.am/docs/api/index.md): API
### Chat
- [List chats](https://developer.ro.am/docs/api/chat-list.md): GET /chat.list
- [Send a message](https://developer.ro.am/docs/api/chat-post.md): POST /chat.post
- [Send a message (Legacy)](https://developer.ro.am/docs/api/chat-send-message.md): POST /chat.sendMessage
- [Post an ephemeral message](https://developer.ro.am/docs/api/chat-post-ephemeral.md): POST /chat.postEphemeral
- [List scheduled messages](https://developer.ro.am/docs/api/chat-scheduled-list.md): GET /chat.scheduled.list
- [Cancel a scheduled message](https://developer.ro.am/docs/api/chat-scheduled-cancel.md): POST /chat.scheduled.cancel
- [Start a streaming message](https://developer.ro.am/docs/api/chat-start-stream.md): POST /chat.startStream
- [Append to a streaming message](https://developer.ro.am/docs/api/chat-append-stream.md): POST /chat.appendStream
- [Stop a streaming message](https://developer.ro.am/docs/api/chat-stop-stream.md): POST /chat.stopStream
- [Update a message](https://developer.ro.am/docs/api/chat-update.md): POST /chat.update
- [Delete a message](https://developer.ro.am/docs/api/chat-delete.md): POST /chat.delete
- [Send a typing indicator](https://developer.ro.am/docs/api/chat-typing.md): POST /chat.typing
- [Get chat messages](https://developer.ro.am/docs/api/chat-history.md): GET /chat.history
- [Search chat messages](https://developer.ro.am/docs/api/chat-search.md): POST /chat.search
- [Resolve a chat link](https://developer.ro.am/docs/api/chat-link-resolve.md): POST /chat.link.resolve
- [Create a chat message link](https://developer.ro.am/docs/api/chat-link-create.md): POST /chat.link.create
- [Unfurl a link](https://developer.ro.am/docs/api/chat-unfurl.md): POST /chat.unfurl
- [Add reaction to message](https://developer.ro.am/docs/api/reaction-add.md): POST /reaction.add
- [Remove reaction from message](https://developer.ro.am/docs/api/reaction-remove.md): POST /reaction.remove
- [List reactions on a message](https://developer.ro.am/docs/api/reaction-list.md): GET /reaction.list
- [Create a file upload](https://developer.ro.am/docs/api/asset-create.md): POST /asset.create
- [Upload an item](https://developer.ro.am/docs/api/item-upload.md): POST /item.upload
- [Post story](https://developer.ro.am/docs/api/story-post.md): POST /story.post
### Users
- [List users](https://developer.ro.am/docs/api/user-list.md): GET /user.list
- [Get user info](https://developer.ro.am/docs/api/user-info.md): GET /user.info
- [User Audit Log](https://developer.ro.am/docs/api/userauditlog-list.md): GET /userauditlog.list
- [Export message events](https://developer.ro.am/docs/api/messageevent-export.md): POST /messageevent.export
### Meetings
- [List conversations](https://developer.ro.am/docs/api/conversation-list.md): GET /conversation.list
- [List meetings](https://developer.ro.am/docs/api/meeting-list.md): GET /meeting.list
- [List meeting recordings (Legacy)](https://developer.ro.am/docs/api/recording-list.md): GET /recording.list
- [Get meeting info](https://developer.ro.am/docs/api/meeting-info.md): GET /meeting.info
- [List meeting participants](https://developer.ro.am/docs/api/meeting-participants.md): GET /meeting.participants
- [Get meeting transcript](https://developer.ro.am/docs/api/meeting-transcript.md): GET /meeting.transcript
- [Search meetings](https://developer.ro.am/docs/api/meeting-search.md): GET /meeting.search
- [Prompt about a meeting](https://developer.ro.am/docs/api/meeting-prompt.md): POST /meeting.prompt
- [Get a shareable meeting link](https://developer.ro.am/docs/api/meeting-share-link.md): POST /meeting.shareLink
- [Create a meeting link](https://developer.ro.am/docs/api/meeting-link-create.md): POST /meeting.link.create
- [Get a meeting link](https://developer.ro.am/docs/api/meeting-link-info.md): POST /meeting.link.info
- [Update a meeting link](https://developer.ro.am/docs/api/meeting-link-update.md): POST /meeting.link.update
- [Create a calendar event](https://developer.ro.am/docs/api/calendar-event-create.md): POST /calendar.event.create
- [List calendar events](https://developer.ro.am/docs/api/calendar-list.md): GET /calendar.list
- [List lobbies](https://developer.ro.am/docs/api/lobby-list.md): GET /lobby.list
- [List lobby bookings](https://developer.ro.am/docs/api/lobby-booking-list.md): GET /lobby.booking.list
### Magicasts
- [List magicasts](https://developer.ro.am/docs/api/magicast-list.md): GET /magicast.list
- [Get magicast info](https://developer.ro.am/docs/api/magicast-info.md): GET /magicast.info
- [Get a shareable Magicast link](https://developer.ro.am/docs/api/magicast-share-link.md): POST /magicast.shareLink
### Groups
- [List groups](https://developer.ro.am/docs/api/group-list.md): GET /group.list
- [List groups (Legacy)](https://developer.ro.am/docs/api/groups-list.md): GET /groups.list
- [Get group info](https://developer.ro.am/docs/api/group-info.md): GET /group.info
- [Create a group](https://developer.ro.am/docs/api/group-create.md): POST /group.create
- [Rename a group](https://developer.ro.am/docs/api/group-rename.md): POST /group.rename
- [Archive a group](https://developer.ro.am/docs/api/group-archive.md): POST /group.archive
- [List group members](https://developer.ro.am/docs/api/group-members.md): GET /group.members
- [Add group members](https://developer.ro.am/docs/api/group-add.md): POST /group.add
- [Remove group members](https://developer.ro.am/docs/api/group-remove.md): POST /group.remove
### App
- [Access token info](https://developer.ro.am/docs/api/token-info.md): GET /token.info
- [Revoke access token](https://developer.ro.am/docs/api/token-revoke.md): POST /token.revoke

## Webhooks API (v1)

Subscribe with **dot** event names (e.g. `chat.message`). Colon names (`chat:message:dm`) are v0-only and return `Unrecognized event` on v1. Deliveries use the common event envelope (`type`, `eventId`, `timestamp`, `apiVersion`, `data`) from version `2026-07-07`. A single event can currently produce two POSTs with the same `webhook-id` (legacy tagged-id body + v1 body) — de-duplicate on `webhook-id`. v1 unsubscribe is JSON `{"id"}`; v0 is form-urlencoded. Subscribing does not probe the destination URL — the first delivery is a real event.

- [API Overview](https://developer.ro.am/docs/webhooks/index.md): Webhooks
- [List webhook subscriptions](https://developer.ro.am/docs/webhooks/webhook-list.md): GET /webhook.list
- [Subscribe to an event webhook](https://developer.ro.am/docs/webhooks/webhook-subscribe.md): POST /webhook.subscribe
- [Unsubscribe from an event webhook](https://developer.ro.am/docs/webhooks/webhook-unsubscribe.md): POST /webhook.unsubscribe
- [List failed webhook deliveries](https://developer.ro.am/docs/webhooks/webhook-deliveries.md): GET /webhook.deliveries
### Events
- [app.uninstalled](https://developer.ro.am/docs/webhooks/app-uninstalled.md): App uninstalled
- [chat.link.shared](https://developer.ro.am/docs/webhooks/chat-link-shared.md): Matching link shared
- [chat.message](https://developer.ro.am/docs/webhooks/chat-message.md): Chat message received
- [chat.reaction](https://developer.ro.am/docs/webhooks/chat-reaction.md): Reaction added or removed
- [lobby.booked](https://developer.ro.am/docs/webhooks/lobby-booked.md): Lobby booking created
- [magicast.created](https://developer.ro.am/docs/webhooks/magicast-created.md): Magicast created
- [meeting.ended](https://developer.ro.am/docs/webhooks/meeting-ended.md): Meeting ended
- [meeting.started](https://developer.ro.am/docs/webhooks/meeting-started.md): Meeting started
- [onair.event.canceled](https://developer.ro.am/docs/webhooks/onair-event-canceled.md): On-Air event canceled
- [onair.event.created](https://developer.ro.am/docs/webhooks/onair-event-created.md): On-Air event created
- [onair.event.updated](https://developer.ro.am/docs/webhooks/onair-event-updated.md): On-Air event updated
- [onair.guest.added](https://developer.ro.am/docs/webhooks/onair-guest-added.md): On-Air guests added
- [onair.guest.rsvp](https://developer.ro.am/docs/webhooks/onair-guest-rsvp.md): On-Air guest RSVP changed
- [token.revoked](https://developer.ro.am/docs/webhooks/token-revoked.md): Token revoked
- [user.status.update](https://developer.ro.am/docs/webhooks/user-status-update.md): User status update

## On-Air API

- [API Overview](https://developer.ro.am/docs/onair-api/index.md): On-Air API
- [Get event info](https://developer.ro.am/docs/onair-api/onair-event-info.md): GET /onair.event.info
- [List events](https://developer.ro.am/docs/onair-api/onair-event-list.md): GET /onair.event.list
- [Create an event](https://developer.ro.am/docs/onair-api/onair-event-create.md): POST /onair.event.create
- [Update an event](https://developer.ro.am/docs/onair-api/onair-event-update.md): POST /onair.event.update
- [Cancel an event](https://developer.ro.am/docs/onair-api/onair-event-cancel.md): POST /onair.event.cancel
- [Get guest info](https://developer.ro.am/docs/onair-api/onair-guest-info.md): GET /onair.guest.info
- [List guests](https://developer.ro.am/docs/onair-api/onair-guest-list.md): GET /onair.guest.list
- [Add guests](https://developer.ro.am/docs/onair-api/onair-guest-add.md): POST /onair.guest.add
- [Update guest RSVP](https://developer.ro.am/docs/onair-api/onair-guest-update.md): POST /onair.guest.update
- [Remove a guest](https://developer.ro.am/docs/onair-api/onair-guest-remove.md): POST /onair.guest.remove
- [List attendance](https://developer.ro.am/docs/onair-api/onair-attendance-list.md): GET /onair.attendance.list

## SCIM 2.0 API (User Provisioning)

- [API Overview](https://developer.ro.am/docs/scim/index.md): Roam HQ SCIM 2.0 API
- [Get Service Provider Config](https://developer.ro.am/docs/scim/03-metadata-service-provider-config.md): GET /ServiceProviderConfig
- [Get Resource Types](https://developer.ro.am/docs/scim/03-metadata-resource-types.md): GET /ResourceTypes
- [List Schemas](https://developer.ro.am/docs/scim/03-metadata-list-schemas.md): GET /Schemas
- [Get Schema](https://developer.ro.am/docs/scim/03-metadata-get-schema.md): GET /Schemas/{schemaId}
- [List Users](https://developer.ro.am/docs/scim/01-users-list.md): GET /Users
- [Create User](https://developer.ro.am/docs/scim/01-users-create.md): POST /Users
- [Get User](https://developer.ro.am/docs/scim/01-users-get.md): GET /Users/{id}
- [Replace User](https://developer.ro.am/docs/scim/01-users-replace.md): PUT /Users/{id}
- [Delete User](https://developer.ro.am/docs/scim/01-users-delete.md): DELETE /Users/{id}
- [Patch User](https://developer.ro.am/docs/scim/01-users-patch.md): PATCH /Users/{id}
- [List Groups](https://developer.ro.am/docs/scim/02-groups-list.md): GET /Groups
- [Create Group](https://developer.ro.am/docs/scim/02-groups-create.md): POST /Groups
- [Get Group](https://developer.ro.am/docs/scim/02-groups-get.md): GET /Groups/{id}
- [Replace Group](https://developer.ro.am/docs/scim/02-groups-replace.md): PUT /Groups/{id}
- [Patch Group](https://developer.ro.am/docs/scim/02-groups-patch.md): PATCH /Groups/{id}
- [Delete Group](https://developer.ro.am/docs/scim/02-groups-delete.md): DELETE /Groups/{id}

## Legacy APIs (still available)

These remain documented for existing integrations. Prefer v1 for new work; see the [migration guide](https://developer.ro.am/docs/guides/migration-v0-to-v1.md).

v1 also keeps three **(Legacy)** routes next to their modern replacements in the API Reference: `chat.sendMessage`, `groups.list`, and `recording.list`. Prefer `chat.post`, `group.list`, and `meeting.list` / `meeting.info`.

### Chat API (Alpha / v0)

- [API Overview](https://developer.ro.am/docs/chat-api/index.md): API v0 Overview
### Chat
- [List chats](https://developer.ro.am/docs/chat-api/chat-list.md): GET /chat.list
- [Post to a chat](https://developer.ro.am/docs/chat-api/chat-post.md): POST /chat.post
- [Update a message](https://developer.ro.am/docs/chat-api/chat-update.md): POST /chat.update
- [Delete a message](https://developer.ro.am/docs/chat-api/chat-delete.md): POST /chat.delete
- [Send a typing indicator](https://developer.ro.am/docs/chat-api/chat-typing.md): POST /chat.typing
- [Get Chat Messages](https://developer.ro.am/docs/chat-api/chat-history.md): GET /chat.history
- [Upload an item](https://developer.ro.am/docs/chat-api/item-upload.md): POST /item.upload
- [Add reaction to message](https://developer.ro.am/docs/chat-api/reaction-add.md): POST /reaction.add
### Users
- [Get info on Address](https://developer.ro.am/docs/chat-api/addr-info.md): GET /addr.info
- [List users](https://developer.ro.am/docs/chat-api/user-list.md): GET /user.list
- [Get user info](https://developer.ro.am/docs/chat-api/user-info.md): GET /user.info
- [Look up user](https://developer.ro.am/docs/chat-api/user-lookup.md): GET /user.lookup
- [User Audit Log](https://developer.ro.am/docs/chat-api/userauditlog-list.md): GET /userauditlog.list
### Groups
- [Create a group](https://developer.ro.am/docs/chat-api/group-create.md): POST /group.create
- [Rename a group](https://developer.ro.am/docs/chat-api/group-rename.md): POST /group.rename
- [Archive a group](https://developer.ro.am/docs/chat-api/group-archive.md): POST /group.archive
- [List group members](https://developer.ro.am/docs/chat-api/group-members.md): GET /group.members
- [Add group members](https://developer.ro.am/docs/chat-api/group-add.md): POST /group.add
- [Remove group members](https://developer.ro.am/docs/chat-api/group-remove.md): POST /group.remove
### App
- [Access token info](https://developer.ro.am/docs/chat-api/token-info.md): GET /token.info
- [Uninstall an app](https://developer.ro.am/docs/chat-api/uninstall-app.md): POST /app.uninstall
### Meetings
- [List meeting transcripts](https://developer.ro.am/docs/chat-api/list-transcripts.md): GET /transcript.list
- [Get meeting transcript](https://developer.ro.am/docs/chat-api/get-transcript.md): GET /transcript.info
- [Prompt a meeting transcript](https://developer.ro.am/docs/chat-api/prompt-transcript.md): POST /transcript.prompt
- [Create a meeting link](https://developer.ro.am/docs/chat-api/meetinglink-create.md): POST /meetinglink.create
- [Get a meeting link](https://developer.ro.am/docs/chat-api/meetinglink-info.md): POST /meetinglink.info
- [Update a meeting link](https://developer.ro.am/docs/chat-api/meetinglink-update.md): POST /meetinglink.update
- [List meetings](https://developer.ro.am/docs/chat-api/meeting-list.md): GET /meeting.list
- [List lobbies](https://developer.ro.am/docs/chat-api/lobby-list.md): GET /lobby.list
- [List lobby bookings](https://developer.ro.am/docs/chat-api/lobby-booking-list.md): GET /lobbyBooking.list

### Webhooks / Events (v0)

Colon event names (`transcript:saved`, `recording:saved`, …). Prefer v1 webhooks above.

- [API Overview](https://developer.ro.am/docs/webhooks-v0-dev/index.md): Webhooks v0 Overview
- [Subscribe to an event webhook](https://developer.ro.am/docs/webhooks-v0-dev/webhook-subscribe.md): POST /webhook.subscribe
- [Unsubscribe from an event webhook](https://developer.ro.am/docs/webhooks-v0-dev/webhook-unsubscribe.md): POST /webhook.unsubscribe
### Events
- [chat.message.channel](https://developer.ro.am/docs/webhooks-v0-dev/chat-message-channel.md): Message received
- [chat.message.dm](https://developer.ro.am/docs/webhooks-v0-dev/chat-message-dm.md): Message received
- [chat.message.reaction](https://developer.ro.am/docs/webhooks-v0-dev/chat-message-reaction.md): Message reaction added
- [lobby.booked](https://developer.ro.am/docs/webhooks-v0-dev/lobby-booked.md): Lobby booking created
- [magicast.created](https://developer.ro.am/docs/webhooks-v0-dev/magicast-created.md): Magicast created
- [onair.event.canceled](https://developer.ro.am/docs/webhooks-v0-dev/onair-event-canceled.md): On-Air event canceled
- [onair.event.created](https://developer.ro.am/docs/webhooks-v0-dev/onair-event-created.md): On-Air event created
- [onair.event.updated](https://developer.ro.am/docs/webhooks-v0-dev/onair-event-updated.md): On-Air event updated
- [onair.guest.added](https://developer.ro.am/docs/webhooks-v0-dev/onair-guest-added.md): Guests added to event
- [onair.guest.rsvp](https://developer.ro.am/docs/webhooks-v0-dev/onair-guest-rsvp.md): Guest RSVP changed
- [recording.saved](https://developer.ro.am/docs/webhooks-v0-dev/recording-saved.md): Recording saved
- [transcript.saved](https://developer.ro.am/docs/webhooks-v0-dev/transcript-saved.md): Transcript saved
- [transcript.started](https://developer.ro.am/docs/webhooks-v0-dev/transcript-started.md): Transcript started
- [user.status.update](https://developer.ro.am/docs/webhooks-v0-dev/user-status-update.md): User status update

## OpenAPI Specifications

- [Roam API v1](https://developer.ro.am/chat-v1.json): Chat, users, groups, meetings, reactions
- [Webhooks API v1](https://developer.ro.am/webhooks-v1.json): Real-time event subscriptions (dot events + envelope)
- [On-Air API](https://developer.ro.am/onair.json): Events, guests, RSVPs, and attendance
- [SCIM 2.0 API](https://developer.ro.am/scim.json): User and group provisioning
- [Chat API v0 (Alpha)](https://developer.ro.am/chat.json): Legacy chat, transcripts, meeting links
- [Webhooks API v0](https://developer.ro.am/webhooks.json): Legacy colon-form event subscriptions

## Instructions for LLM Agents

When helping users with the Roam API:
1. Prefer **v1 only** (`/docs/api`, `/docs/webhooks`, `chat-v1.json`, `webhooks-v1.json`) for new integrations — never invent `/v0` or colon event names for new work
2. Use the `.md` URLs above to fetch detailed endpoint documentation
3. OpenAPI specs contain complete request/response schemas
4. All APIs require Bearer token authentication (API Key, OAuth, or PAT)
5. Pin shapes with `Roam-Version` (current default `2026-08-07`; see [API Versioning](https://developer.ro.am/docs/guides/api-versioning.md)); webhook payloads are versioned at subscribe time
6. v1 webhook bodies use the envelope — route on `type`, read the payload from `data`, de-dupe on `eventId`
7. Chat post endpoint is `chat.post` (not `chat.sendMessage`); list groups is `group.list` (not `groups.list`); meeting events are `meeting.ended` (not `transcript:saved`)
8. For OAuth apps, guide users to Roam Administration > Developer; PATs are under User Settings > Developer