# Quick Start

## Choose a path

| Goal | Guide |
|------|-------|
| Post alerts into a group (CI/CD, monitoring) | **[Notification bot](/docs/guides/quickstart-notification-bot)** |
| Receive messages and reply | **[Interactive bot](/docs/guides/quickstart-interactive-bot)** |
| Ask AI about meetings / chat (MCP) | **[AI agent / MCP](/docs/guides/quickstart-ai-agent)** |
| Automate without writing code | **[Webhook Relays](/docs/integrations/webhook-relays)**, **[Zapier](/docs/integrations/zapier)**, **[GitHub Actions](/docs/integrations/github-actions)** |
| Let visitors book time in a public lobby | **[Lobby agents](/docs/integrations/lobby-agents)** |
| Show that someone is on a call / in an external meeting | **[External activity](/docs/guides/user-activity)** |
| Grant a client email limited access hosted by a member | **[Guest Badges](/docs/guides/guest-badges)** |

## About Roam HQ

Roam HQ is an all-in-one virtual office for distributed teams: chat, video meetings,
transcripts, and a shared map headquarters.

For third-party OAuth (authorize URL, code exchange, refresh, token lifetimes),
see the **[OAuth & Authentication](/docs/guides/oauth)** guide. For the full
scope list, see **[Scopes](/docs/guides/scopes)**.

## Creating an Application

In [the Roam settings](https://ro.am/s/), visit the “Developer” tab. On this page, you can view all the apps created.

To access the API, you need to create an Application.

1. Navigate to _Roam Administration_ > _Developer_ (by clicking the gear icon labeled _Settings_ at the bottom right of the map).
   The list of API clients is displayed.
2. Click _Add ApiClient_. A form appears.
3. Enter a name & description, and select the _Authorization type_. For now,
   choose _API key_, but typically you would select _OAuth_, if the app acts on
   behalf of a user, or _API Key_ if the app is not connected to a specific
   user.
4. Click Add to save the app. A section showing the Client ID, Client Secret,
   and other settings appears.
5. Select the _Access Scopes_ based on the needs of the application. For now,
   choose `group:read`. See the [Scopes catalog](/docs/guides/scopes) for the full set.
6. Save your changes.

To test your API key, you can list groups from the command line:

```shell
$ curl -H "Authorization: Bearer $API_KEY" \
  https://api.ro.am/v1/group.list
```

That's it! You have used the Roam API. Continue with a
[guided quickstart](#choose-a-path) or the full [API Reference](/docs/api/api).

## Next steps

- **[API Reference](/docs/api/api)** — the endpoint catalog, plus the conventions every
  client needs: [access models](/docs/api/api#access-models),
  [authentication failures](/docs/api/api#authentication-failures),
  [pagination](/docs/api/api#pagination), [rate limiting](/docs/api/api#rate-limiting),
  and [common error responses](/docs/api/api#common-error-responses)
- **[Access Models](/docs/guides/access-models)** — organization vs personal access,
  endpoint compatibility, and choosing a model
- **[Chat](/docs/guides/chat)** — when an app can read, post, react, and receive
  chat webhooks (org vs personal, Slack bot token vs user token)
- **[Responses and Errors](/docs/guides/responses-and-errors)** — success envelope,
  cursors, and `missing_scope` details
- **[Error Codes](/docs/guides/error-codes)** — the full machine-readable code catalog
- **[SDKs](/docs/guides/sdks)** — TypeScript (`@roamhq/sdk`), Go (`ro.am/roamhq`), and Python (`roamhq`) clients that handle pagination, retries, and typed errors