Skip to main content

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, 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:

$ 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 for forwarding notifications from external services into chat, plus other pre-built integrations 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 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:

StatusMeaning
400 Bad RequestInvalid request parameters
401 UnauthorizedMissing or invalid authentication
403 ForbiddenValid auth but insufficient access (e.g., bot not in chat, lacking group access)
413 Payload Too LargeRequest body exceeds size limits
429 Too Many RequestsRate limit exceeded (see Rate Limiting above)
500 Internal Server ErrorServer-side error

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

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