# 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" https://api.ro.am/v1/groups.list
```

- [Quick Start Guide](https://developer.ro.am/docs/intro.md): Create an API client and make your first request

## Guides

- [Access Models](https://developer.ro.am/docs/guides/access-models.md)
- [Block Kit](https://developer.ro.am/docs/guides/block-kit.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)
- [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 events](/docs/webhooks/chat-message.md) - Subscribe to incoming messages
- [/chat.post](/docs/chat-api/chat-post.md) - Send responses
- [/chat.typing](/docs/chat-api/chat-typing.md) - Show typing indicators

### Post-Meeting Automation
Get notified when recordings and transcripts are ready for processing.
- [transcript:saved](/docs/webhooks/transcript-saved.md) - Webhook for new transcripts
- [/transcript.info](/docs/chat-api/get-transcript.md) - Get summaries and action items

### Send Notifications
Post alerts from CI/CD, monitoring, or ticketing systems into Roam groups.
- [/chat.sendMessage](/docs/roam-api/send-message.md) - Post messages to groups
- [/groups.list](/docs/roam-api/list-groups.md) - Find group IDs

### Compliance & Archival
Export daily message archives for compliance, legal holds, or data warehousing.
- [/messageevent.export](/docs/roam-api/messageevent-export.md) - Export archives

### On-Air Event Management
Create events, manage guest lists, and track RSVPs programmatically. Sync with external event platforms or build custom registration flows.
- [/onair.event.create](/docs/onair-api/onair-event-create.md) - Create events
- [/onair.guest.add](/docs/onair-api/onair-guest-add.md) - Add guests
- [onair.guest.rsvp](/docs/webhooks/onair-guest-rsvp.md) - RSVP webhook

### User Provisioning
Automatically sync users from Okta, Azure AD, or other identity providers.
- [SCIM Users](/docs/scim/01-users-list.md)
- [SCIM Groups](/docs/scim/02-groups-list.md)

## Roam HQ API (v1 - Stable)

- [API Overview](https://developer.ro.am/docs/roam-api/index.md): Roam HQ API
- [Send a Roam message](https://developer.ro.am/docs/roam-api/send-message.md): POST /chat.sendMessage
- [List groups](https://developer.ro.am/docs/roam-api/list-groups.md): GET /groups.list
- [List meeting recordings](https://developer.ro.am/docs/roam-api/list-recordings.md): GET /recording.list
- [Export message events](https://developer.ro.am/docs/roam-api/messageevent-export.md): POST /messageevent.export
- [List magicasts](https://developer.ro.am/docs/roam-api/list-magicasts.md): GET /magicast.list
- [Get magicast](https://developer.ro.am/docs/roam-api/get-magicast.md): GET /magicast.info

## On-Air API (v1 - Stable)

- [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

## Chat API (Alpha)

- [API Overview](https://developer.ro.am/docs/chat-api/index.md): Roam HQ Chat API (Alpha)
### 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

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

## Webhooks / Events API (Alpha)

- [API Overview](https://developer.ro.am/docs/webhooks/index.md): Roam HQ Events API (Alpha)
- [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

## OpenAPI Specifications

- [Roam HQ API v1](https://developer.ro.am/openapi.json): Stable API for messaging and recordings
- [On-Air API v1](https://developer.ro.am/onair.json): Events, guests, RSVPs, and attendance
- [Chat API (Alpha)](https://developer.ro.am/chat.json): Advanced chat, meetings, transcripts
- [SCIM 2.0 API](https://developer.ro.am/scim.json): User and group provisioning
- [Webhooks API](https://developer.ro.am/webhooks.json): Real-time event subscriptions

## Instructions for LLM Agents

When helping users with the Roam API:
1. Use the `.md` URLs above to fetch detailed endpoint documentation
2. The OpenAPI specs contain complete request/response schemas
3. All APIs require Bearer token authentication
4. The v1 API is stable; v0 (Alpha) APIs may change
5. For OAuth apps, guide users to Roam Administration > Developer