Skip to main content

​
Overview

Delete a monitor group. If the group contains monitors, you can either force delete (unassigning monitors to root level) or reassign monitors to another group.
Groups with monitors cannot be deleted unless you provide force: true or specify a reassign_to_group_id. Without either option, the API will return an error.

​
Authentication

Requires API Key authentication via the X-API-Key header or Bearer token. 
X-API-Key: YOUR_API_KEY

​
Request

curl -X DELETE https://api.uptimeio.com/api/groups/550e8400-e29b-41d4-a716-446655440000 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "force": true
  }'

​
Path Parameters

ParameterTypeDescription
groupIdUUIDThe ID of the group to delete

​
Request Body

FieldTypeDefaultDescription
forcebooleanfalseForce delete group even if it contains monitors. Monitors will be unassigned (moved to root level).
reassign_to_group_idUUID-ID of another group to reassign monitors to before deletion. Takes precedence over force.
If the group has monitors, you must provide either force: true or reassign_to_group_id. If both are provided, reassign_to_group_id takes precedence.

​
Response

Returns the deletion result with the number of monitors affected. 
{
  "success": true,
  "data": {
    "success": true,
    "monitors_unassigned": 5
  }
}
This response contains two success fields with different meanings:
  • Outer success: Indicates the API call completed without errors
  • Inner data.success: Indicates whether the group was actually deleted (found and removed from the database)
Both will typically be true on a successful deletion. The inner data.success would be false if the group ID was valid but the row was not found for deletion (e.g., already deleted or race condition).

​
Response Fields

FieldTypeDescription
successbooleanWhether the group was actually found and deleted
monitors_unassignednumberNumber of monitors that were unassigned or reassigned

​
Status Codes

StatusDescription
200Group deleted successfully
400Validation error (group has monitors without force/reassign option, or target group not found)
401Unauthorized (missing or invalid token)
403Forbidden (no permission to delete group)
404Group not found
500Internal server error

​
Examples

​
Delete Empty Group

Delete a group that has no monitors: 
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 '{}'
Response: 
{
  "success": true,
  "data": {
    "success": true,
    "monitors_unassigned": 0
  }
}

​
Force Delete Group with Monitors

Delete a group and unassign its monitors to root level: 
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 '{
    "force": true
  }'
Response: 
{
  "success": true,
  "data": {
    "success": true,
    "monitors_unassigned": 12
  }
}

​
Delete Group and Reassign Monitors

Delete a group and reassign all its monitors to another group: 
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: 
{
  "success": true,
  "data": {
    "success": true,
    "monitors_unassigned": 12
  }
}

​
Error Codes

​
Group Has Active Checks

Returned when trying to delete a group that contains monitors without providing force or reassign_to_group_id: 
{
  "success": false,
  "error": {
    "code": "GROUP_HAS_CHECKS",
    "message": "Cannot delete group with active checks. Use force=true or provide reassign_to_group_id"
  }
}

​
Target Group Not Found

Returned when the specified reassign_to_group_id does not exist or is not accessible: 
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to delete group"
  }
}

​
Group Not Found

Returned when the group to delete does not exist or you don’t have access: 
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to delete group"
  }
}

​
Internal Error

Returned when an unexpected error occurs during deletion: 
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to delete group"
  }
}