---
title: "Create an agent group"
method: POST
path: "/agent-groups"
tags: ["Agent Groups"]
---

# Create an agent group

`POST /agent-groups`

## Request

- Base URL: `https://api.mnemom.ai/v1`
- URL: `https://api.mnemom.ai/v1/agent-groups`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-Mnemom-Api-Key`

Create a new agent group (a logical tag) in an organization. Group names must be unique among active groups within the organization. Optionally seed the group with an initial set of agent members.

## Request body

- object
  - `org_id` string, required: Organization that owns this group
  - `name` string, required: Display name (unique among active groups in the org)
  - `description` string, nullable: Optional description
  - `color` string, nullable: Optional group colour as #rrggbb hex. Omit or null for no colour.
  - `agent_ids` string[]: Agent IDs to add as initial members (optional)
  - `metadata` object: Freeform metadata

## Response `201`

Group created

- object
  - `group_id` string
  - `org_id` string
  - `name` string
  - `color` string, nullable
  - `status` 'active'
  - `member_count` integer
  - `members` object[]

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Forbidden
- `404`: Resource not found
- `409`: Name conflict — a group with this name already exists among the org's active groups (name uniqueness is case-insensitive). The body carries `error.code: "group_name_taken"` and, when the existing group is resolvable, a safe `existing_group` summary a client can steer the user onto. Both the pre-check path and the concurrent-create race path return an identical body.
- `429`: Rate-limit exceeded. The global per-IP limiter (100 requests/minute, applied to every `/v1/*` route) rejected this request. Back off until the window resets — `Retry-After` carries the cooldown in seconds and `X-RateLimit-Reset` the absolute reset time.
- `500`: Server error — request was well-formed but the server failed to fulfill it. Typically a downstream dependency (DB / RPC / external API) returned an unexpected error.
- `503`: An upstream dependency is currently unavailable. The request was not processed; retry after the cooldown window.

---

[API](https://skmtc.dev/mnemom/apis/mnemom-api.md) · [All operations](https://skmtc.dev/mnemom/apis/mnemom-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemom/apis/mnemom-api/revisions/274b7a6ea182?raw)