Skip to main content

​
Endpoint

POST /groups

​
Authentication

This endpoint requires authentication via API key. Include your API key in the X-API-Key header: 
X-API-Key: ca_your_api_key_here

​
Request Body

The request body must be a JSON object with the following fields:

​
Required Fields

FieldTypeDescription
namestringName of the new group. Must be at least 1 character

​
Optional Fields

FieldTypeDescription
users_idsarrayIdentifiers of the users to add as initial members. Defaults to an empty array

​
Request Example

curl -X POST https://platform.chamelio.ai/groups \
  -H "X-API-Key: ca_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Legal",
    "users_ids": [1001, 1002]
  }'

import requests

url = "https://platform.chamelio.ai/groups"
headers = {
    "X-API-Key": "ca_your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "name": "Legal",
    "users_ids": [1001, 1002]
}

response = requests.post(url, headers=headers, json=payload)
print(response.json())

const response = await fetch('https://platform.chamelio.ai/groups', {
  method: 'POST',
  headers: {
    'X-API-Key': 'ca_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Legal',
    users_ids: [1001, 1002]
  })
});

const data = await response.json();
console.log(data);

​
Response

​
Success Response

Status Code: 200 OK 
{
  "group_id": 14,
  "name": "Legal",
  "member_user_ids": [1001, 1002],
  "created_at": "2025-06-04T10:15:00Z"
}

​
Response Fields

FieldTypeDescription
group_idintegerUnique identifier of the newly created group
namestringName of the newly created group
member_user_idsarrayIdentifiers of the users added to the group
created_atstringISO 8601 timestamp of when the group was created

​
Error Responses

​
400 Bad Request

Returned when the request is invalid — for example, a group name that already exists or an invalid user identifier. The detail reflects the underlying validation error. 
{
  "detail": "Group with this name already exists"
}

​
401 Unauthorized

Returned when authentication fails. See the authentication errors section for details. 
{
  "detail": "Invalid API key"
}

​
422 Unprocessable Entity

Returned when the request body fails validation — for example, an empty name. 
{
  "detail": "Validation error"
}

​
500 Internal Server Error

Returned when the group could not be created due to a server error. 
{
  "detail": "Failed to create group"
}

​
Notes

The new group is always created in the organization that owns the API key. The users_ids you supply are returned as member_user_ids in the response. Retrieve valid user identifiers via GET /users.

​
Use Cases

This endpoint is useful for:
  • Group provisioning - Programmatically create groups from an external system
  • Team setup - Seed a new group with its initial members in a single request
  • Access organization - Structure users into groups for downstream workflows