---
title: "Create Group"
method: POST
path: "/api/v1/groups/"
tags: ["User APIs", "groups"]
---

# Create Group

`POST /api/v1/groups/`

Create new group, optionally setting its MCP period limit, MCP access
and Block role in the same request.

## Request body

- GroupCreate
  - `name` string, required
  - `description` string, nullable
  - `transaction_limit` number, nullable
  - `allocated_amount` number, nullable
  - `client_id` string, uuid, required
  - `is_default` boolean, nullable
  - `is_active` boolean, nullable
  - `meta_data` object, nullable
  - `user_ids` string[], nullable
  - `block_role` 'block_user' | 'block_admin' — Additive Block role values stored directly on ``users.block_role`` and ``groups.block_role`` (``block_role_enum`` Postgres enum). Matches the snake_case value set used elsewhere in the Block domain.
  - `mcp_period_limit` number, nullable
  - `mcp_access_revoked` boolean, nullable

## Response `200`

Successful Response

- GroupRead
  - `name` string, required
  - `description` string, nullable
  - `transaction_limit` number, nullable
  - `allocated_amount` number, nullable
  - `client_id` string, uuid, required
  - `is_default` boolean, nullable
  - `is_active` boolean, nullable
  - `meta_data` object, nullable
  - `user_ids` string[], nullable
  - `block_role` 'block_user' | 'block_admin' — Additive Block role values stored directly on ``users.block_role`` and ``groups.block_role`` (``block_role_enum`` Postgres enum). Matches the snake_case value set used elsewhere in the Block domain.
  - `id` string, uuid, required
  - `key` string, required
  - `current_consumption` number, nullable
  - `mcp_period_limit` number, nullable
  - `mcp_period_consumption` number, nullable
  - `mcp_period_reset_date` string, date-time, nullable
  - `mcp_period_next_reset_date` string, date-time, nullable
  - `mcp_period_start_date` string, date-time, nullable
  - `mcp_access_revoked` boolean, nullable
  - `mcp_access_revoked_at` string, date-time, nullable

## Other responses

- `422` — Validation Error

## Changes

- **2026-08-21** `a8ca30023371` — 1 breaking, 22 info
  - the response's body type/format changed from ``/`` to `object`/`` for status `200`
  - added the new optional request property `mcp_access_revoked`
  - added the new optional request property `mcp_period_limit`
  - added the optional property `allocated_amount` to the response with the `200` status
  - …19 more

[Change history](https://skmtc.dev/carbonarc/apis/carbon-arc-client-admin-api/changes/api/v1/groups/post.md)

---

[API](https://skmtc.dev/carbonarc/apis/carbon-arc-client-admin-api.md) · [All operations](https://skmtc.dev/carbonarc/apis/carbon-arc-client-admin-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/carbonarc/carbon-arc-client-admin-api/revisions/56e2edae9dfe/schema)