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

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

## Example

```bash theme={null}
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`

```json theme={null}
{
  "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](/api-reference/groups/get); 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`). |

```json theme={null}
{
  "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"
      }
    ]
  }
}
```

<Note>
  The exact wording of entries in `details` comes from the validator and can change. Rely on `code` and `path`.
</Note>

See [Errors](/api-reference/errors) for the full error reference.


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