> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chamelio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Group

> Create a new user group in your organization, optionally seeded with members.

## Endpoint

```
POST /groups
```

## Authentication

This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:

```bash theme={null}
X-API-Key: ca_your_api_key_here
```

## Request Body

The request body must be a JSON object with the following fields:

### Required Fields

| Field  | Type   | Description                                         |
| ------ | ------ | --------------------------------------------------- |
| `name` | string | Name of the new group. Must be at least 1 character |

### Optional Fields

| Field       | Type  | Description                                                                    |
| ----------- | ----- | ------------------------------------------------------------------------------ |
| `users_ids` | array | Identifiers of the users to add as initial members. Defaults to an empty array |

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://platform.chamelio.ai/groups \
    -H "X-API-Key: ca_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "Legal",
      "users_ids": [1001, 1002]
    }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://platform.chamelio.ai/groups"
  headers = {
      "X-API-Key": "ca_your_api_key_here",
      "Content-Type": "application/json"
  }
  payload = {
      "name": "Legal",
      "users_ids": [1001, 1002]
  }

  response = requests.post(url, headers=headers, json=payload)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://platform.chamelio.ai/groups', {
    method: 'POST',
    headers: {
      'X-API-Key': 'ca_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'Legal',
      users_ids: [1001, 1002]
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "group_id": 14,
  "name": "Legal",
  "member_user_ids": [1001, 1002],
  "created_at": "2025-06-04T10:15:00Z"
}
```

### Response Fields

| Field             | Type    | Description                                      |
| ----------------- | ------- | ------------------------------------------------ |
| `group_id`        | integer | Unique identifier of the newly created group     |
| `name`            | string  | Name of the newly created group                  |
| `member_user_ids` | array   | Identifiers of the users added to the group      |
| `created_at`      | string  | ISO 8601 timestamp of when the group was created |

## Error Responses

### 400 Bad Request

Returned when the request is invalid — for example, a group name that already exists or an invalid user identifier. The `detail` reflects the underlying validation error.

```json theme={null}
{
  "detail": "Group with this name already exists"
}
```

### 401 Unauthorized

Returned when authentication fails. See the [authentication errors](/api-reference/introduction#authentication-errors) section for details.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 422 Unprocessable Entity

Returned when the request body fails validation — for example, an empty `name`.

```json theme={null}
{
  "detail": "Validation error"
}
```

### 500 Internal Server Error

Returned when the group could not be created due to a server error.

```json theme={null}
{
  "detail": "Failed to create group"
}
```

## Notes

<Info>
  The new group is always created in the organization that owns the API key. The `users_ids` you supply are returned as `member_user_ids` in the response. Retrieve valid user identifiers via [`GET /users`](/api-reference/endpoint/users/list).
</Info>

## Use Cases

This endpoint is useful for:

* **Group provisioning** - Programmatically create groups from an external system
* **Team setup** - Seed a new group with its initial members in a single request
* **Access organization** - Structure users into groups for downstream workflows