Create Group

​

Create a group in a tenant, optionally with members and workshop items. The API key's user becomes the group owner. Creating a group also requires the Create Groups permission (the default roles with Manage Groups have it). Without tenant_id the group is created in your MSP's own company. Group names do not have to be unique.

Requires an API key for an MSP user whose role includes the Manage Groups permission. Tenant (company) users, including tenant admins, receive 403. Groups in tenants your MSP does not manage are never returned or changed.

Body·

required
application/json
  • name
    Type: string
    min length:  
    3
    max length:  
    72
    required

    Group name: 3-72 characters, letters, numbers and spaces only

  • description
    Type: stringnullable

    Group description

  • members
    Type: array of string

    User HashIDs to add as members. All must belong to the group's tenant.

  • tenant_id
    Type: stringnullable

    Tenant ID (e.g. tenant_abc123). Defaults to your MSP's own company, not a tenant: pass it when creating a group for a customer.

  • workshop_items
    Type: array of AdminWorkshopItemInput

    Apps, workflows and agents to share with the group

    Properties: 2

Responses

  • application/json
  • application/json
  • application/json
  • application/json
  • application/json
Request Example for post/admin/groups
curl https://ai.hatz.ai/v1/admin/groups \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_SECRET_TOKEN' \
  --data '{
  "name": "Sales",
  "description": "Sales team",
  "tenant_id": "tenant_abc123",
  "members": [
    "user_n55abP89ZowO6iKAx7vqWjrqnZ",
    "user_ExxypMkWV0PLDUAyLpdJlOEJ69"
  ]
}'

{
  "id": "group_X7VAK72dp5nX3Cd6JXwdPg6OxD",
  "name": "Sales",
  "description": "Sales team",
  "tenant_id": "tenant_abc123",
  "owner": {
    "id": "user_gE4JlrAxlgKXEfvA3jZexy6Pxq",
    "email": "admin@yourmsp.com",
    "first_name": "Alex",
    "last_name": "Admin"
  },
  "members": [
    {
      "id": "user_n55abP89ZowO6iKAx7vqWjrqnZ",
      "email": "sam@example.com",
      "first_name": "Sam",
      "last_name": "Rivera"
    }
  ],
  "workshop_items": [
    {
      "id": "5143da6d-c5de-4c2f-a0b6-3df4d0e542f0",
      "item_type": "agent"
    }
  ],
  "created_at": "2026-11-05T20:02:42.715415+00:00",
  "updated_at": "2026-11-05T20:02:42.715415+00:00"
}

Group created

Previous
List Groups
Next
Get Group