# Quick Start

## About Roam HQ

Roam HQ is an all-in-one virtual office designed to bring a whole distributed company together in one headquarters.

Roam HQ makes companies:

- more _productive_ with shorter meetings
- more _connected_ with a map that gives a feeling of working together without meeting
- & Roam saves companies money with our all-in-one bundle

NOTE: To create API clients, you must be an admin of the Roam. You can either generate an API key or OAuth client ID/secret.

## 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 `groups:read`.
6. Save your changes.

To test your API key, you can list groups from the command line. Find your Roam
ID from _Roam Administration > Roam_ and run the following command:

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

That's it! You have used the Roam API. Being a REST API, you can use your
preferred programming language to build any automation you desire.

However, you may not need to write any code to accomplish your goal.
Roam offers [Webhook Relays](/docs/integrations/webhook-relays) for forwarding notifications from external services into chat, plus other [pre-built integrations](/docs/integrations/zapier) for common scenarios.

## Access Models

Roam APIs support two access models:

- **Organization access** -- For admin-built integrations that operate across the entire workspace. The integration acts as an app with its own bot persona. Authenticate with an API Key or OAuth (admin consent).
- **Personal access** -- For integrations that act on behalf of a specific user, seeing only that user's data and sending messages as them. Authenticate with OAuth or a Personal Access Token (user consent).

A single OAuth app can support both models. The access model is selected when the user authorizes the app.

See the [Access Models guide](/docs/guides/access-models) for a full comparison, endpoint compatibility matrix, and guidance on choosing the right model.

## Rate Limiting

API requests are rate limited to prevent abuse. The limits are:

- **Burst**: 10 requests
- **Sustained rate**: 1 request per second

When you exceed the rate limit, the API returns HTTP `429 Too Many Requests` with a `Retry-After` header indicating when you can retry (typically 10 seconds).

**Best practices:**
- Implement exponential backoff when you receive a 429 response
- Respect the `Retry-After` header value
- Batch operations where possible to reduce request count

## Pagination

List endpoints return paginated results. The pagination behavior varies by endpoint:

**Cursor-based pagination** (most endpoints):
- `cursor`: Opaque string from a previous response's `nextCursor` field. Do not parse or construct cursors yourself.
- `limit`: Number of results per page. Default is typically 10, maximum is typically 100.

**Date-range pagination** (some endpoints like `transcript.list`, `meeting.list`):
- `after`: Return items after this date (RFC3339 or YYYY-MM-DD format)
- `before`: Return items before this date
- When `after` is specified, results are returned in ascending order; otherwise descending.

Check individual endpoint documentation for specific pagination parameters and limits.

## Common Error Responses

The API uses standard HTTP status codes. Common errors include:

| Status | Meaning |
|--------|---------|
| `400 Bad Request` | Invalid request parameters |
| `401 Unauthorized` | Missing or invalid authentication |
| `403 Forbidden` | Valid auth but insufficient access (e.g., bot not in chat, lacking group access) |
| `413 Payload Too Large` | Request body exceeds size limits |
| `429 Too Many Requests` | Rate limit exceeded (see Rate Limiting above) |
| `500 Internal Server Error` | Server-side error |

All error responses include a JSON body with an `error` field describing the issue:

```json
{"error": "Description of what went wrong"}
```