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

# Update Group

> Rename a group, change its description, or move it under another parent

## Overview

Updates a group. Send only the fields you want to change.

`PUT /api/groups/{groupId}`

## Authentication

`X-API-Key: YOUR_API_KEY` (`read_write` scope) or `Authorization: Bearer YOUR_JWT`.

## Path parameters

| Parameter | Type | Description |
| - | - | - |
| `groupId` | UUID | The group to update. |

## Request body

| Field | Type | Description |
| - | - | - |
| `name` | string | 1-100 characters. Must be unique within the project (case-sensitive). |
| `description` | string | Up to 500 characters. |
| `parent_group_id` | UUID | Move the group under this parent. Must not be the group itself or one of its descendants. |

<Note>
  `parent_group_id` must be a UUID. There is no way to move a group back to the top level by sending `null`; a `null` value fails validation.
</Note>

## Example

```bash theme={null}
curl -X PUT https://api.uptimeio.com/api/groups/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production Web", "description": "Customer-facing web services" }'
```

## Response

`200 OK` with the updated [group object](/api-reference/groups/create#group-object).

```json theme={null}
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "0b0f7a0e-2c3d-4f55-9a11-6f1c2f1d9a10",
    "project_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "name": "Production Web",
    "description": "Customer-facing web services",
    "created_at": "2026-09-30T10:30:00.000Z",
    "updated_at": "2026-09-30T10:30:00.000Z",
    "check_count": 0,
    "monitors": [],
    "children": [],
    "path": []
  }
}
```

## Errors

| Status | Code | When |
| - | - | - |
| `400` | `VALIDATION_ERROR` | Body failed validation (`Invalid request data`). |
| `400` | `CIRCULAR_REFERENCE` | `Cannot create circular group reference`. |
| `400` | `DUPLICATE_NAME` | `Group name already exists in this project`. The new name is used by another group in the project, under any parent. |
| `401` | `MISSING_AUTH` / `INVALID_API_KEY` | Missing or invalid credentials. |
| `403` | `READ_ONLY_API_KEY` | The API key has read-only scope. |
| `404` | `RESOURCE_NOT_FOUND` | `Group not found`. The group does not exist, or belongs to another organization or project. |
| `500` | `INTERNAL_ERROR` | `Failed to update group`. Also returned today when the nesting limit would be exceeded. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.