---
title: "Create or replace project group"
method: PUT
path: "/v1/project_group"
tags: ["ProjectGroups"]
---

# Create or replace project group

`PUT /v1/project_group`

## Request

- Base URL: `https://api.braintrust.dev`
- URL: `https://api.braintrust.dev/v1/project_group`
- Auth: one of:
  - HTTP bearer
  - none

Create or replace project group. If there is an existing project group with the same name as the one specified in the request, will replace the existing project group with the provided fields

## Request body

- CreateProjectGroup
  - `name` string, required: Name of the project group
  - `description` string, nullable: Textual description of the project group
  - `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 project group belongs in.

## Response `200`

Returns the new project group object

- ProjectGroup: A project group is a collection of projects which inherit access from project_group_projects ACLs. The group's definition and membership are governed separately by project_group ACLs.
  - `id` string, uuid, required: Unique identifier for the project group
  - `org_id` string, uuid, required: Unique id for the organization that the project group belongs under It is forbidden to change the org after creating a project group
  - `user_id` string, uuid, nullable: Identifies the user who created the project group
  - `created` string, date-time, nullable: Date of project group creation
  - `name` string, required: Name of the project group
  - `description` string, nullable: Textual description of the project group
  - `deleted_at` string, date-time, nullable: Date of project group deletion, or null if the project group is still active
  - `member_projects` string[], required: Sorted ids of active projects in this project group. Modifying membership requires project_group:update on the group.

## 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.)

## Changes

- **2026-10-30** `8f5039399f77`: 2 breaking
  - the request property `description` became not nullable
  - the request property `org_name` became not nullable
- **2026-09-03** `ebac33c1422e`: 1 breaking
  - request body became required
- **2026-08-13** `e05ef145579d`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/braintrustdata/apis/braintrust-api/changes/v1/project_group/put.md)

---

[API](https://skmtc.dev/braintrustdata/apis/braintrust-api.md) - [All operations](https://skmtc.dev/braintrustdata/apis/braintrust-api/llms.txt) - [OpenAPI document](https://skmtc.dev/braintrustdata/apis/braintrust-api/revisions/19184ec94018?raw)