Overview
Create a new monitor group to organize and manage your monitoring checks. Groups can be nested to create hierarchical structures. When creating a child group, specify the parent_group_id to establish the relationship.
Authentication
Requires API Key authentication via the X-API-Key header.
Request
The parent_group_id is optional. If not provided, the group will be created at the root level.
curl -X POST https://api.uptimeio.com/api/groups \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{
"name": "Production Services",
"description": "Critical production monitoring group"
}'
Request Body
| Field | Type | Required | Description |
|---|
name | string | Yes | Group name (1-100 characters) |
description | string | No | Group description (max 500 characters) |
parent_group_id | UUID | No | ID of parent group for nested hierarchy |
Response
Returns the created group object with a 201 status code.
{
"success": true,
"data": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"organization_id": "org-uuid-here",
"project_id": "project-uuid-here",
"name": "Production Services",
"description": "Critical production monitoring group",
"parent_group_id": null,
"check_count": 0,
"created_at": "2024-12-26T10:30:00Z",
"created_by": "user-uuid-here"
}
}
Response Fields
| Field | Type | Description |
|---|
id | UUID | Unique identifier for the group |
organization_id | UUID | Organization this group belongs to |
project_id | UUID | Project this group belongs to |
name | string | Group name |
description | string | Group description |
parent_group_id | UUID | null | Parent group ID if nested |
check_count | number | Number of monitors in this group |
created_at | timestamp | Creation timestamp |
created_by | UUID | null | User who created the group |
Status Codes
| Status | Description |
|---|
201 | Group created successfully |
400 | Validation error (missing required fields, invalid format) |
401 | Unauthorized (missing or invalid token) |
403 | Forbidden (no permission to create groups) |
Examples
Create Root Level Group
curl -X POST https://api.uptimeio.com/api/groups \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "API Services",
"description": "REST API and GraphQL endpoints"
}'
Create Child Group
curl -X POST https://api.uptimeio.com/api/groups \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Web Services",
"description": "Frontend and web services",
"parent_group_id": "550e8400-e29b-41d4-a716-446655440000"
}'
Error Codes
Validation Error
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Invalid request data",
"details": [
{
"code": "too_small",
"message": "String must contain at least 1 character(s)",
"path": ["name"]
}
]
}
}
Unauthorized Error
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication required"
}
}
Circular Reference Error
Returned when the specified parent_group_id would create a circular hierarchy (e.g., setting a group’s parent to one of its descendants).
{
"success": false,
"error": {
"code": "CIRCULAR_REFERENCE",
"message": "Cannot create circular group reference"
}
}
Duplicate Name Error
Returned when a group with the same name already exists in the organization.
{
"success": false,
"error": {
"code": "DUPLICATE_NAME",
"message": "Group name already exists in this organization"
}
}
Maximum Depth Exceeded Error
Returned when creating a nested group would exceed the maximum nesting depth.
{
"success": false,
"error": {
"code": "MAX_DEPTH_EXCEEDED",
"message": "Maximum nesting depth exceeded"
}
}
Rate Limiting
API requests are subject to rate limiting. Check the response headers for rate limit information:
X-RateLimit-Limit: Maximum requests per windowX-RateLimit-Remaining: Remaining requestsX-RateLimit-Reset: Unix timestamp when limit resets
