Skip to content
Changelog

Report a bug

Roam integration: operations for AI agents

Roam connects to Type.com as an integration. This page lists the 109 operations documented for Claude and Codex in Type.com: 49 read, 44 write, 16 destructive.

About Roam

Roam HQ provides APIs for secure messaging, chat, file sharing, and collaboration with enterprise-grade security and compliance features.

Categories: Email & Messaging

How to connect Roam to Type.com

Access
Organization connection: one shared account for the workspace.

To add the connection, follow the steps in Space connections.

Documented operations

109 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.

109 operations listed.

Chat

  • Read

    List chats

    List accessible chats — DMs, multi-DMs, group chats, all-hands "team Roam" groups, and meeting chats. Personal access tokens are backed by the user's inbox: chats are ordered by most recent activity and include lastMessageTime, isUnread, preview, isMuted, and isPinned.

  • Read

    List scheduled messages

    Lists pending messages scheduled via /chat.post's sendAt that have not been sent yet. Results are ordered ascending by sendAt (soonest first). Sent and canceled messages are not returned.

  • Read

    Get chat messages

    List messages in a chat, filtered by date range (after/before). Messages with contentType of text, voice, or poll are returned. System messages and other content types are excluded.

  • Read

    Search chat messages

    Full-text search over the caller's accessible messages. Returns full-fidelity messages — text, items, voice, polls, blocks, and mentions — hydrated through the same pipeline as /chat.history. All fields are optional.

  • Read

    List reactions on a message

    List reactions on a specific message, grouped by emoji (Slack-style {name, count, users}). Poll votes are returned separately in pollVotes rather than folded into reactions. users contains visible principal IDs only.

  • Write

    Send a message

    Send a message to a chat. Messages can be plain markdown text, rich Block Kit layouts, or polls.

  • Write

    Post an ephemeral message

    Post an ephemeral message — visible to a single member of a chat, with an "Only you can see this" header — without posting anything the other members can see.

  • Write

    Start a streaming message

    Open a streaming message and post its first content. Streaming lets a bot deliver a message incrementally — recipients see the text fill in live (with a "typing…" indicator) instead of waiting for the full response. This is useful for AI agents that produce text token-by-token.

  • Write

    Append to a streaming message

    Append a chunk of text to an open stream (see /chat.startStream). Each chunk is broadcast to recipients as a delta, so the message appears to fill in live. Call as many times as needed before /chat.stopStream.

  • Write

    Stop a streaming message

    Finalize an open stream (see /chat.startStream) into a single persisted chat message and return its timestamp. Optionally include trailing text to append before finalizing.

  • Write

    Update a message

    Edit a previously posted bot message. The updated message can contain plain markdown text or rich Block Kit layouts. The bot must own the message being updated (matched by address ID).

  • Write

    Send a typing indicator

    Notify other chat participants that you are working on a response. If they have the chat open, they will see "(Bot name) is typing...". The indicator lasts 6 seconds. Re-send every 5 seconds to keep it visible while you work. Longer gaps will let it expire between pings.

  • Write

    Resolve a chat link

    Parse a Roam chat deep link (e.g. https://ro.am/r//d/...) and return the referenced message. When the caller has access to the referenced chat, the full message is returned and readable is true.

  • Write

    Create a chat message link

    Create a shareable Roam link to a specific chat message. Opening the link in Roam navigates to that message in its chat.

  • Write

    Unfurl a link

    Attach app-provided preview cards to links in an existing text message. Every map key must be an exact URL currently present in the message and must match one of the app's registered unfurl domains. Validation is atomic: if any entry is invalid, no previews are changed.

  • Write

    Add reaction to message

    Add a reaction to a message in a chat. To react to a thread reply, provide the threadTimestamp of the parent message and the timestamp of the specific reply. Access: The organization bot or personal-token owner must be a member of the chat (403 notinchat otherwise).

  • Write

    Create a file upload

    Create a file asset and get back a self-describing instruction for uploading its bytes — the JSON-friendly way to attach a file (image, PDF, document, …) to a message, supply media for a story, or host an avatar image.

  • Write

    Upload an item

    Upload a file so that it can be sent as a chat message attachment. The returned object contains an item ID which can be used with chat.post. Unlike other endpoints, this uses raw binary upload with metadata in HTTP headers rather than JSON.

  • Write

    Post story

    Posts a story to your Roam. Stories are short photo or video updates that appear above your profile picture for your teammates, and expire 24 hours after posting. Posting Flow 1.

  • Destructive

    Cancel a scheduled message

    Cancels a pending message scheduled via /chat.post's sendAt, so it will never be delivered. Pending scheduled messages can be discovered with /chat.scheduled.list. Only the credential's bot identity that scheduled the message may cancel it.

  • Destructive

    Delete a message

    Delete a previously posted bot message. The bot must own the message being deleted (matched by address ID). Personal access tokens always send as their bot persona and may only delete messages that personal bot posted.

  • Destructive

    Remove reaction from message

    Remove a reaction from a message in a chat. Only reactions added by the authenticated app can be removed. To remove a reaction from a thread reply, provide the threadTimestamp of the parent message and the timestamp of the specific reply.

Users

  • Read

    List users

    List workspace members, or hydrate an explicit ordered set of principal IDs. Without ids, this is the active workspace member directory: guests, bots, and archived/deactivated members are never enumerated. Members are returned in the order they were added to the account.

  • Read

    Get user info

    Resolve a v1 principal by ID, or look up a workspace member by email. ID lookup resolves active or archived members, guests, and authorized automated actors (classic bots, agents, assistants, and coworkers).

  • Read

    Get a user's status bubble

    Returns the shared UI/API thought bubble, or null when no live bubble exists. Expired bubbles are omitted before storage cleanup runs. See Status bubbles. Access: Organization and Personal. Organization credentials may target an active user in the workspace.

  • Read

    List a user's external activities

    Return every currently live external activity for a user — every integration's rows, not only yours. Expired rows are omitted even before the server reaper runs. Not paginated; ordered newest startedAt first.

  • Read

    User Audit Log

    Get a list of user audit log entries for the account. Required scope: userauditlog:read --- OpenAPI Spec: chat-v1.json

  • Read

    Export message events

    Obtain a daily message event export containing DMs and group chats within your account.

  • Read

    List Users

    Returns a paginated list of users in your Roam organization. Filtering: Supports SCIM filter expressions, e.g., filter=userName eq "alice@example.com". Pagination: Use startIndex (1-based) and count to paginate through results.

  • Read

    Get User

    Retrieves a single user by their Roam Person ID. The response includes all user attributes, the active status, and the Roam role extension. See RFC 7644 §3.4.1 for SCIM resource retrieval.

  • Write

    Set a user's Will Return / Out of Roam

    Record an absence on a workspace member — the same Will Return Today / Out of Roam field the desktop client writes, already readable via user.info?expand=status and user.status.update. This is not external activity.

  • Write

    Clear a user's Will Return / Out of Roam

    Remove the Will Return / Out of Roam previously written with user.status.set or the desktop client. Clears both same-day Will Return Today and persistent Out of Roam. Clearing when nothing is set still returns 204. This call does not change check-in status.

  • Write

    Set a user's status bubble

    Replaces the shared UI/API thought bubble. Text is trimmed and limited to 1–20 Unicode code points. Omitted or null ttlSeconds defaults to 86400; integers from 300 through 86400 are accepted. Durations below 5 minutes or above 24 hours are rejected.

  • Write

    Clear a user's status bubble

    Clears the shared thought bubble, including a bubble written by the UI or another integration. Repeating clear is a successful no-op. This does not clear Will Return or external activities. See Status bubbles. Access: Organization and Personal.

  • Write

    Set a user's external activity

    Paint a badge (and optional glow) on a user's seat for work happening outside Roam — a phone call, a browser meeting, a CRM session. Pass dnd: true to also put their assigned office in Do Not Disturb.

  • Write

    Clear a user's external activity

    End an activity previously created with user.activity.set. The row is keyed by this integration plus userId and externalId — you cannot clear another app's activity. Clearing a missing, already-cleared, or already-expired externalId still returns 204.

  • Write

    Create User

    Provisions a new user in your Roam organization. Required fields: userName, name.givenName, name.familyName, and emails[0].value.

  • Write

    Patch User

    Partially updates a user. PATCH supports the same mutable surface as PUT (Replace User).

  • Destructive

    Replace User

    Fully replaces a user's attributes. You must provide all required fields in the request body.

  • Destructive

    Delete User

    Archives a user in Roam. This is a soft delete — the user's data is retained but they lose access.

Meetings

  • Read

    List conversations

    Lists conversations (meetings) that occurred in your Roam, with participant details. Access: - Organization with admin:meetings:read (or a grandfathered roam-wide API key): all conversations in the workspace.

  • Read

    List meetings

    List meetings, ordered newest-first. Access: Organization and Personal. Personal tokens return meetings the authenticated user participated in.

  • Read

    Get meeting info

    Get detailed information about a specific meeting, including AI-generated summary, action items, and chapters. Participants are included inline up to the maxParticipants limit. For meetings with more participants, use /meeting.participants to paginate through the full list.

  • Read

    List meeting participants

    Paginate through all participants of a meeting. This is the dedicated endpoint for retrieving the full participant list, complementing the capped inline participants in /meeting.info. Pagination uses an opaque cursor (not a row offset).

  • Read

    Get meeting transcript

    Retrieve the transcript for a meeting. Supports content negotiation: - JSON (default): Returns structured transcript with cues containing speaker IDs, text, and timing - WebVTT: Set Accept: text/vtt header to receive standard WebVTT format with speaker voice tags Access: Organiz…

  • Read

    Search meetings

    AI-powered search across meeting transcripts and summaries. Access: Personal access only. Organization (account-level) tokens are not supported. Required scope: meetings:read --- OpenAPI Spec: chat-v1.json

  • Read

    Get a meeting link

    Get a meeting link. Access: Organization and Personal. Personal tokens may only read meeting links where the authenticated user is the host. Required scope: meetinglink:read --- OpenAPI Spec: chat-v1.json

  • Read

    List calendar events

    List events from the authenticated user's connected calendars within a date range. Pulls events from every active personal calendar attached to the user (e.g. Google, Microsoft) and merges them into a single chronological list. Canceled events are omitted.

  • Read

    List lobbies

    Lists active lobbies in your account. A lobby URL has the form ro.am/{handle} or ro.am/{handle}/{slug}. - The "handle" is the first path segment - The "slug" is the optional second path segment.

  • Read

    List lobby bookings

    Lists bookings for a specific lobby configuration, filtered by date range (after/before). The ordering of results depends on ascending and after: - ascending=true sorts in forward chronological order (oldest first).

  • Write

    Prompt about a meeting

    Ask an AI question about a meeting's transcript content. Returns a natural language response based on the meeting transcript. Access: Organization and Personal.

  • Write

    Create a meeting link

    Create a meeting link. Access: Organization and Personal. In Organization mode, specify the host by email. In Personal mode, the host defaults to the authenticated user. Required scope: meeting:write or meetinglink:write --- OpenAPI Spec: chat-v1.json

  • Write

    Update a meeting link

    Update a meeting link. Access: Organization and Personal. Personal tokens may only update meeting links where the authenticated user is the host. Required scope: meetinglink:write --- OpenAPI Spec: chat-v1.json

  • Write

    Create a calendar event

    Create a calendar event on the host's connected calendar. A Roam meeting link is automatically attached and email notifications are sent to attendees. The event is written to the first active, writable calendar associated with the host.

Magicasts

  • Read

    List magicasts

    List Magicasts in your account. Results are most recent first when neither ascending nor after is set. See ascending to change the order. Returns metadata only (id, name, createdAt, ownerId, coverImageUrl).

  • Read

    Get magicast info

    Get details for a single Magicast by ID, including transcript cues, chapters, video status, a signed video download URL when ready, and a player URL if a share link already exists. This is the content endpoint. /magicast.list returns metadata only.

Folders

  • Read

    List folders

    List folders of meetings and Magicasts, newest first. Access: Organization and Personal. Personal tokens return only folders the token owner belongs to, each with that person's role (admin or viewer). Organization tokens return every folder in the account, and role is omitted.

  • Read

    Get folder info

    Get one folder by ID: name, item count, creation time, and — for Personal access — the caller's role. Use folder.contents for the meetings and Magicasts filed in it, and folder.members for who can see it. Access: Organization and Personal.

  • Read

    List folder contents

    List the meetings and Magicasts filed in a folder, newest first, with each item's metadata. Reading the folder is what grants access to these rows. A meeting or Magicast is included even when the caller would not see it on meeting.list or magicast.list.

  • Read

    List folder members

    List everyone who belongs to a folder and their role (admin or viewer). The full member list is returned in one response. Every userId is a principal ID. Resolve names with user.info or user.list, which require user:read. Access: Organization and Personal.

  • Write

    Create a folder

    Create a folder for meetings and Magicasts. The new folder is visible only to its members: file items with folder.addContents and share it with folder.addMembers. Access: Organization and Personal.

  • Write

    Rename a folder

    Rename a folder by ID. Access: Organization and Personal. Personal tokens need the admin role on the folder: a viewer gets 403 accessdenied, and a folder the token's owner does not belong to returns 404 foldernotfound. Organization tokens can change every folder in the account.

  • Write

    File meetings and Magicasts into a folder

    File up to 100 meetings and Magicasts into a folder in one call. Every folder member can then read them with meeting.info, meeting.transcript, magicast.info, and the related endpoints. Filing an item that is already in the folder succeeds and changes nothing.

  • Write

    Add folder members or change their roles

    Add up to 100 people to a folder with the same role, or change the role of people who are already members. admin members can manage the folder; viewer members can see it and everything filed in it. Demoting the last admin to viewer returns 409 conflict.

  • Destructive

    Delete a folder

    Delete a folder. Members lose the access the folder gave them; the meetings and Magicasts filed in it are not deleted, and anyone who could see an item another way keeps that access. Access: Organization and Personal.

  • Destructive

    Remove meetings and Magicasts from a folder

    Remove up to 100 meetings and Magicasts from a folder in one call. The items are not deleted; folder members lose the access the folder gave them. Removing an item that is not in the folder succeeds and changes nothing. Access: Organization and Personal.

  • Destructive

    Remove folder members

    Remove up to 100 people from a folder. They lose the access the folder gave them. Removing the last admin returns 409 conflict; promote someone else with folder.addMembers first. Access: Organization and Personal.

Groups

  • Read

    List groups

    Lists non-archived groups accessible to the caller. Filter by name with query (ranked text match), restrict by group type with type, and paginate with limit / cursor. Access: Organization and Personal. Required scope: group:read --- OpenAPI Spec: chat-v1.json

  • Read

    Get group info

    Get information about a specific group by its ID or name. Provide either id or name, not both. Required scope: group:read --- OpenAPI Spec: chat-v1.json

  • Read

    List group members

    List members in a group with their roles. Apps may list members if one of the following conditions is true: 1. It is a public group in their Roam. 2. They are a member of the group.

  • Read

    List Groups

    Returns a paginated list of groups in your Roam organization. Pagination: Use startIndex (1-based) and count to paginate through results. Note: The filter parameter is accepted but currently ignored for Groups. See RFC 7644 §3.4.2 for SCIM filtering and pagination.

  • Read

    Get Group

    Retrieves a single group by its Roam Address ID. The response includes the group's displayName and members array containing user IDs. See RFC 7644 §3.4.1 for SCIM resource retrieval.

  • Write

    Create a group

    Create a group chat. Groups which specify at least one admin will operate in an "Admin only" management mode, where only admins may change settings. Otherwise, all members have that capability. Groups require at least one member.

  • Write

    Rename a group

    Rename a group by ID. Apps may only rename groups for which they are an admin. Required scope: group:write --- OpenAPI Spec: chat-v1.json

  • Write

    Add group members

    Add one or more group members with specified roles. Members can be specified by user ID or email address. Each member must be assigned a role (member or admin). Adding an unrecognized email does not grant a Guest Badge.

  • Write

    Join a group

    Join a public group as the calling identity (Slack conversations.join). - Org tokens add the bot address as a member. - Personal tokens add the owner person, never the PAT bot address. - Private groups cannot be self-joined (403).

  • Write

    Create Group

    Creates a new group in your Roam organization. Required fields: displayName (max 64 characters). Optional: Include members array with user IDs to add initial members.

  • Write

    Patch Group

    Partially updates a group. Use this to add or remove members without replacing the entire group.

  • Destructive

    Archive a group

    Archive a group by ID. Apps may only archive groups for which they are an admin. Required scope: group:write --- OpenAPI Spec: chat-v1.json

  • Destructive

    Remove group members

    Remove one or more group members. Members can be specified by user ID or email address. Apps may remove members from a group if one of the following conditions is true: 1. It is a public group in their Roam. 2. They are a member of the group.

  • Destructive

    Replace Group

    Fully replaces a group's attributes. The entire members list is replaced with the provided values. Required fields: displayName (max 64 characters). Note: This is a full replacement — any members not included in the request will be removed from the group.

  • Destructive

    Delete Group

    Archives a group in Roam. This is a soft delete — the group data is retained but becomes inactive.

Guest Badges

  • Read

    List Guest Badges

    List issued Guest Badges. Organization tokens return every issued badge in the workspace. Personal tokens return only badges the token owner issued. This is the issued (host) view — the same rows guest.badge.create returns — not the guest's hidden-inbox view.

  • Write

    Grant a Guest Badge

    Grant a Guest Badge so an email that is not a workspace member can visit a host in Roam. This is not an On-Air event guest. It is also not implied by group.add: adding an email to a group does not mint a badge or send the invite.

  • Write

    Update a Guest Badge

    Update visitPermission on an existing Guest Badge. guest.badge.create is idempotent and does not change visitPermission on an existing grant. Use this endpoint to flip on-map visit access after create.

  • Destructive

    Revoke a Guest Badge

    Revoke Guest Badge(s) for an email. If only one host in the workspace has granted this email, hostUserId may be omitted. If several hosts have, pass hostUserId to pick which grant to revoke (400 missingparameter otherwise). Same-host alias rows are all revoked together.

App

  • Read

    Access token info

    Get information about the access token, including the authenticated user/bot and granted scopes. No specific scope required. --- OpenAPI Spec: chat-v1.json

  • Destructive

    Revoke access token

    Permanently revoke the presented OAuth access token and its refresh token. After a successful response the grant is dead — refresh will not resurrect it; the client must re-authorize.

Events

  • Read

    Get event info

    Returns details for a single On-Air event. Access: Organization and Personal. Required scope: onair:read --- OpenAPI Spec: onair.json

  • Read

    List events

    Returns a paginated list of On-Air events for the organization. Results are sorted by start time in descending order (most recent first). Access: Organization and Personal. Required scope: onair:read --- OpenAPI Spec: onair.json

  • Write

    Create an event

    Creates a new On-Air event. The calendar host must be a member of the organization. When using a personal access token, calendarHostEmail must match the authenticated user. Optionally provide display hosts in the hosts array.

  • Write

    Update an event

    Updates an existing On-Air event. Only the fields provided in the request body are updated; omitted fields remain unchanged. Access: Organization and Personal. Required scope: onair:write --- OpenAPI Spec: onair.json

  • Destructive

    Cancel an event

    Cancels an On-Air event. This action cannot be undone. Access: Organization and Personal. Required scope: onair:write --- OpenAPI Spec: onair.json

Guests

  • Read

    Get guest info

    Returns details for a single On-Air event guest. Access: Organization and Personal. Required scope: onair:read --- OpenAPI Spec: onair.json

  • Read

    List guests

    Returns a paginated list of guests for an On-Air event. Optionally filter by RSVP status. Results are sorted by creation time in descending order (most recently added first). Access: Organization and Personal. Required scope: onair:read --- OpenAPI Spec: onair.json

  • Write

    Add guests

    Adds one or more guests to an On-Air event. Access: Organization and Personal. Required scope: onair:write --- OpenAPI Spec: onair.json

  • Write

    Update guest RSVP

    Updates the RSVP status of a guest. Access: Organization and Personal. Required scope: onair:write --- OpenAPI Spec: onair.json

  • Destructive

    Remove a guest

    Removes a guest from an On-Air event. Access: Organization and Personal. Required scope: onair:write --- OpenAPI Spec: onair.json

Attendance

  • Read

    List attendance

    Returns the attendance report for an On-Air event, combining RSVP data with join/duration information. Guests with RSVP records are listed first, followed by any additional attendees who joined without an RSVP. Access: Organization and Personal.

Metadata

  • Read

    Get Service Provider Config

    Returns Roam's SCIM capabilities and supported features. Use this endpoint to discover which SCIM operations are supported. No authentication required for this discovery endpoint. See RFC 7644 §4 for the SCIM service provider configuration specification.

  • Read

    Get Resource Types

    Returns the list of resource types supported by Roam: User and Group. No authentication required for this discovery endpoint. See RFC 7644 §4 for the SCIM resource types specification.

  • Read

    List Schemas

    Returns all SCIM schemas supported by Roam, including the core User and Group schemas, Roam's custom role extension (urn:ro.am:params:scim:schemas:extension:roam:2.0:User), and the standard enterprise-user extension (urn:ietf:params:scim:schemas:extension:enterprise:2.0:User).

  • Read

    Get Schema

    Returns the definition of a specific SCIM schema by its URN identifier. No authentication required for this discovery endpoint.

Webhook.list

  • Read

    List webhook subscriptions

    List all webhook subscriptions owned by the authenticated API client. The response includes both dynamic subscriptions (created via /webhook.subscribe) and static subscriptions configured in the Roam Administration UI.

Webhook.subscribe

  • Write

    Subscribe to an event webhook

    Create or update a webhook subscription for a given event. If a subscription already exists for the same event and URL, its filter is updated instead of creating a duplicate.

Webhook.unsubscribe

  • Write

    Unsubscribe from an event webhook

    Remove a webhook subscription by ID. The request body is JSON: {"id": " "}. This differs from v0, which expects application/x-www-form-urlencoded with the same id field. Sending JSON to /v0/webhook.unsubscribe returns id parameter required.

Webhook.deliveries

  • Read

    List failed webhook deliveries

    List recent failed webhook delivery attempts for the authenticated API client, newest first by default (see ascending).

See How connections work for access and permissions, or browse all integrations.