# Create a group

`POST /group.create`

## Description

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. Users can be specified by user ID or email address.

**Required scope:** `group:write`

---

**OpenAPI Spec:** [chat-v1.json](https://developer.ro.am/chat-v1.json)

## Authentication

```
Authorization: Bearer YOUR_API_KEY
```

## Request Body

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `name` | string | Yes | Name of the group |
| `description` | string | No | Description of the group |
| `private` | boolean | No | Whether the group is private (default false) |
| `enforceThreads` | boolean | No | Whether to enforce threaded conversations |
| `members` | object[] | Yes | Group members with their roles |

**members** (array item):

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `userId` | string | Yes | User ID or email address |
| `role` | "member" | "admin" | Yes | Role for this member |

## Responses

### 200 - Group created successfully

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `id` | string | Yes | The group's unique identifier |
| `chatId` | string | No | The group's channel chat ID. Populated by `group.create` and `group.info` (the channel chat is created together with the group), and used to post to or read the channel via the chat endpoints.  |
| `name` | string | Yes | Name of the group |
| `type` | "standard" | "magicast" | "meeting" | "roam" | "onair" | "community" | Yes | The type of group: - `standard` - A regular channel created by users - `magicast` - A Magicast channel - `meeting` - A meeting channel - `roam` - The main Roam channel (one per workspace) - `onair` -  |
| `accessMode` | "public" | "private" | No | Whether the group is public or private |
| `groupManagement` | "allMembers" | "groupAdminsOnly" | No | Who can manage group settings and membership |
| `enforceThreadedMode` | boolean | No | Whether the group enforces threaded conversations |
| `dateCreated` | string | No | When the group was created |
| `imageUrl` | string | No | URL of the group's image |


#### Example Response

```json
{
  "id": "88bebce7-6cbb-4666-96f9-5c02d73e6661",
  "chatId": "",
  "name": "Engineering Team",
  "type": "standard",
  "accessMode": "public",
  "groupManagement": "groupAdminsOnly",
  "enforceThreadedMode": true,
  "dateCreated": "2026-01-21T10:30:00Z"
}
```

### 400 - Bad request.

### 401 - Presented invalid authentication credentials.

### 405 - An unsupported method was requested.

### 500 - An internal error occurred.

---

*Machine-readable API documentation.*
*Full documentation: https://developer.ro.am/docs/api/group-create*