Create Group

Create a monitor group, optionally nested under a parent group

Overview

Creates a group for organizing monitors. Groups can be nested (up to 10 levels) by passing parent_group_id. Group names must be unique within a project, across all parents (case-sensitive). A name used under one parent cannot be reused under another.

POST /api/groups

Authentication

Send either header:

• X-API-Key: YOUR_API_KEY (the key must have read_write scope)
• Authorization: Bearer YOUR_JWT

The group is created in your default project. To target another project, add X-Project-ID: PROJECT_ID.

Request body

Field	Type	Required	Description
name	string	Yes	1-100 characters. Leading and trailing whitespace is trimmed.
description	string	No	Up to 500 characters.
parent_group_id	UUID	No	ID of an existing group to nest under. Omit for a top-level group.

Response

201 Created

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "organization_id": "0b0f7a0e-2c3d-4f55-9a11-6f1c2f1d9a10",
    "project_id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "created_by": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Production Services",
    "description": "Critical production monitoring group",
    "created_at": "2026-09-30T10:30:00.000Z",
    "updated_at": "2026-09-30T10:30:00.000Z",
    "check_count": 0,
    "monitors": [],
    "children": [],
    "path": []
  }
}

Group object

Field	Type	Description
id	UUID	Group identifier.
organization_id	UUID	Owning organization.
project_id	UUID	Owning project.
created_by	UUID	User who created the group (omitted if unknown).
name	string	Group name.
description	string	Description (omitted if empty).
parent_group_id	UUID	Parent group (omitted for top-level groups).
created_at	string	ISO 8601 creation time.
updated_at	string	ISO 8601 time. Currently equal to created_at.
check_count	number	Number of monitors in the group.
monitors, children, path	array	Populated only by Get Group; empty elsewhere.

Errors

Status	Code	Cause
400	VALIDATION_ERROR	Body failed validation. details lists the Zod issues.
400	CIRCULAR_REFERENCE	The parent would create a loop.
400	DUPLICATE_NAME	Group name already exists in this project. Names are unique per project regardless of parent.
400	MAX_DEPTH_EXCEEDED	Maximum nesting depth of 10 levels exceeded.
401	MISSING_AUTH / INVALID_API_KEY	Missing or invalid credentials.
403	READ_ONLY_API_KEY	The API key has read-only scope.
500	INTERNAL_ERROR	Unexpected failure (Failed to create group).

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request data",
    "details": [
      {
        "origin": "string",
        "code": "too_small",
        "minimum": 1,
        "path": ["name"],
        "message": "Too small: expected string to have >=1 characters"
      }
    ]
  }
}

The exact wording of entries in details comes from the validator and can change. Rely on code and path.

See Errors for the full error reference.

Example

cURL

curl -X POST https://api.uptimeio.com/api/groups \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Services",
    "description": "Critical production monitoring group"
  }'