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

# Delete Group

> Delete a group, optionally reassigning its monitors

## Overview

Permanently deletes a group and any groups nested under it. Monitors in the group are not deleted: they are either moved to another group or left ungrouped.

`DELETE /api/groups/{groupId}`

If the group contains monitors you must pass `force: true` (leave them ungrouped) or `reassign_to_group_id` (move them).

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

## Request body

The body is optional. Send none to delete without options. If you send one, it must be valid JSON.

| Field | Type | Description |
| - | - | - |
| `force` | boolean | Delete even if the group contains monitors; they become ungrouped. Default `false`. |
| `reassign_to_group_id` | UUID | Move the group's monitors to this group before deleting. Must be an existing group in the same project. |

## Examples

Delete an empty group:

```bash theme={null}
curl -X DELETE https://api.uptimeio.com/api/groups/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: YOUR_API_KEY"
```

Delete a group and move its monitors:

```bash theme={null}
curl -X DELETE https://api.uptimeio.com/api/groups/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reassign_to_group_id": "660e8400-e29b-41d4-a716-446655440001" }'
```

## Response

`200 OK`

```json theme={null}
{
  "success": true,
  "data": {
    "success": true,
    "monitors_unassigned": 3
  }
}
```

| Field | Type | Description |
| - | - | - |
| `data.success` | boolean | `true` when the group was deleted. |
| `data.monitors_unassigned` | number | How many monitors were in the group (they were moved or left ungrouped, depending on your options). |

## Errors

| Status | Code | When |
| - | - | - |
| `400` | `VALIDATION_ERROR` | The body is not valid JSON (`Request body must be valid JSON`) or a field has the wrong type (`Invalid request data`). |
| `400` | `GROUP_HAS_CHECKS` | `Cannot delete group with active checks. Use force=true or provide reassign_to_group_id`. |
| `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`, or `Target group not found` for an unknown `reassign_to_group_id`. |
| `500` | `INTERNAL_ERROR` | `Failed to delete group`. |


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