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

Example

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"
  }'

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	When
`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.

Introduction

Monitors

Groups

Incidents

Status Pages

Status Page Incidents

Overview

Authentication

Request body

Example

Response

Group object

Errors

​Overview

​Authentication

​Request body

​Example

​Response

​Group object

​Errors

Overview

Authentication

Request body

Example

Response

Group object

Errors