---
title: "Create group"
method: POST
path: "/v1/group"
tags: ["Groups"]
---

# Create group

`POST /v1/group`

Create a new group. If there is an existing group with the same name as the one specified in the request, will return the existing group unmodified

## Request body

- CreateGroup
  - `name` string, required — Name of the group
  - `description` string, nullable — Textual description of the group
  - `member_users` string[], nullable — Ids of users which belong to this group
  - `member_groups` string[], nullable — Ids of the groups this group inherits from An inheriting group has all the users contained in its member groups, as well as all of their inherited users
  - `org_name` string, nullable — For nearly all users, this parameter should be unnecessary. But in the rare case that your API key belongs to multiple organizations, you may specify the name of the organization the group belongs in.

## Response `200`

Returns the new group object

- Group — A group is a collection of users which can be assigned an ACL Groups can consist of individual users, as well as a set of groups they inherit from
  - `id` string, uuid, required — Unique identifier for the group
  - `org_id` string, uuid, required — Unique id for the organization that the group belongs under It is forbidden to change the org after creating a group
  - `user_id` string, uuid, nullable — Identifies the user who created the group
  - `created` string, date-time, nullable — Date of group creation
  - `name` string, required — Name of the group
  - `description` string, nullable — Textual description of the group
  - `deleted_at` string, date-time, nullable — Date of group deletion, or null if the group is still active
  - `member_users` string[], nullable — Ids of users which belong to this group
  - `member_groups` string[], nullable — Ids of the groups this group inherits from An inheriting group has all the users contained in its member groups, as well as all of their inherited users

## Other responses

- `400` — The request was unacceptable, often due to missing a required parameter
- `401` — No valid API key provided
- `403` — The API key doesn’t have permissions to perform the request
- `429` — Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
- `500` — Something went wrong on Braintrust's end. (These are rare.)

---

[API](https://skmtc.net/braintrustdata/apis/braintrust-api.md) · [All operations](https://skmtc.net/braintrustdata/apis/braintrust-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/braintrustdata/braintrust-api/revisions/9d216c8243fe/schema)