Update Group

Update an existing user group

PUT /groups/{groupId}

Update Group

cURL

curl --request PUT \
  --url https://secureai.hiperai.ai/api/external/groups/{groupId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Updated Engineering Team",
  "description": "Updated software engineering team",
  "users": [
    "60a7c8f5e8b4f5001f7a8c24",
    "60a7c8f5e8b4f5001f7a8c26",
    "60a7c8f5e8b4f5001f7a8c27"
  ],
  "status": "Active"
}
'

200

{
  "success": true,
  "message": "Group updated successfully",
  "group": {
    "id": "60a7c8f5e8b4f5001f7a8c25",
    "name": "Updated Engineering Team",
    "description": "Updated software engineering team",
    "status": "Active",
    "userCount": 3,
    "users": [
      {
        "id": "60a7c8f5e8b4f5001f7a8c24",
        "name": "John Doe",
        "email": "[e-mail]"
      }
    ],
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Update Group

Update an existing user group with new information, description, or metadata.

Endpoint

PUT /groups/{groupId}

Description

This endpoint allows administrators to update an existing user group. You can modify the group name, description, metadata, and other properties. The group must exist and you must have appropriate permissions to update it.

Authentication

Required: API Key with admin privileges

Authorization: Bearer sk-your-api-key-here

Path Parameters

Parameter	Type	Required	Description
groupId	string	Yes	The unique identifier of the group to update

Request Body

Parameter	Type	Required	Description
name	string	No	New name for the group
description	string	No	New description for the group
users	array	No	Array of user IDs to assign to the group
status	string	No	Group status

Example Request

{
  "name": "Updated Engineering Team",
  "description": "Updated software engineering and development team",
  "users": ["60a7c8f5e8b4f5001f7a8c24", "60a7c8f5e8b4f5001f7a8c26", "60a7c8f5e8b4f5001f7a8c27"],
  "status": "Active"
}

Success Response

Status Code: 200 OK

{
  "success": true,
  "message": "Group updated successfully",
  "group": {
    "id": "60a7c8f5e8b4f5001f7a8c25",
    "name": "Updated Engineering Team",
    "description": "Updated software engineering and development team",
    "status": "Active",
    "userCount": 3,
    "users": [
      {
        "id": "60a7c8f5e8b4f5001f7a8c24",
        "name": "John Doe",
        "email": "[e-mail]"
      },
      {
        "id": "60a7c8f5e8b4f5001f7a8c26",
        "name": "Jane Smith",
        "email": "[e-mail]"
      },
      {
        "id": "60a7c8f5e8b4f5001f7a8c27",
        "name": "Bob Wilson",
        "email": "[e-mail]"
      }
    ],
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the operation was successful
message	string	Success message
group	object	Updated group object
group.id	string	Unique group identifier
group.name	string	Updated group name
group.description	string	Updated group description
group.status	string	Group status
group.userCount	integer	Number of users in the group
group.users	array	Array of user objects in the group
group.users[].id	string	User ID
group.users[].name	string	User name
group.users[].email	string	User email
group.createdAt	string	Original creation timestamp
group.updatedAt	string	Last update timestamp

Example Usage

JavaScript

const updateGroup = async (groupId, updateData) => {
  const response = await fetch(`https://{customer.name}.hiperai.ai/api/external/groups/${groupId}`, {
    method: 'PUT',
    headers: {
      'Authorization': 'Bearer sk-your-api-key-here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(updateData)
  });
  
  return await response.json();
};

// Example usage
const updateData = {
  name: "Updated Engineering Team",
  description: "Updated software engineering and development team",
  users: ["60a7c8f5e8b4f5001f7a8c24", "60a7c8f5e8b4f5001f7a8c26", "60a7c8f5e8b4f5001f7a8c27"],
  status: "Active"
};

const result = await updateGroup('60a7c8f5e8b4f5001f7a8c25', updateData);
console.log('Updated group:', result.group);

Python

import requests

def update_group(group_id, update_data):
    url = f"https://{customer.name}.hiperai.ai/api/external/groups/{group_id}"
    headers = {
        "Authorization": "Bearer sk-your-api-key-here",
        "Content-Type": "application/json"
    }
    
    response = requests.put(url, headers=headers, json=update_data)
    return response.json()

# Example usage
update_data = {
    "name": "Updated Engineering Team",
    "description": "Updated software engineering and development team",
    "users": ["60a7c8f5e8b4f5001f7a8c24", "60a7c8f5e8b4f5001f7a8c26", "60a7c8f5e8b4f5001f7a8c27"],
    "status": "Active"
}

result = update_group("60a7c8f5e8b4f5001f7a8c25", update_data)
print("Updated group:", result["group"])

cURL

curl -X PUT "https://{customer.name}.hiperai.ai/api/external/groups/60a7c8f5e8b4f5001f7a8c25" \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Engineering Team",
    "description": "Updated software engineering and development team",
    "users": ["60a7c8f5e8b4f5001f7a8c24", "60a7c8f5e8b4f5001f7a8c26", "60a7c8f5e8b4f5001f7a8c27"],
    "status": "Active"
  }'

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Group name cannot be empty",
    "details": {
      "field": "name",
      "value": ""
    }
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Cannot update this group"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "GROUP_NOT_FOUND",
    "message": "Group not found"
  }
}

409 Conflict

{
  "success": false,
  "error": {
    "code": "GROUP_NAME_EXISTS",
    "message": "Group name already exists"
  }
}

429 Too Many Requests

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "retryAfter": 60
  }
}

Use Cases

• Group Management: Update group information and descriptions
• User Assignment: Assign new users to the group
• Name Changes: Rename groups for better clarity
• Status Updates: Change group status
• Team Updates: Update group information when team structure changes

Rate Limits

• Default: 50 requests per minute
• Daily: 5,000 requests per day
• Monthly: 150,000 requests per month

Notes

• This endpoint is only accessible by administrators
• Partial Updates: Only include fields you want to change
• User Assignment: Can assign new users to the group
• Name Validation: Group names must be unique
• Flat Response: Response is not nested under data object
• User Validation: User IDs are validated before assignment
• The updatedAt timestamp is automatically updated

Authorizations

Authorization · string · header · required

API key authentication using Bearer token format. Example: Authorization: Bearer sk-your-api-key-here

Path Parameters

groupId · string · required

Group ID to update

Body

application/json

name · string

Group name

Example:

"Updated Engineering Team"

description · string

Group description

Example:

"Updated software engineering team"

users · string[]

Array of user IDs to assign to the group

Example:

[
  "60a7c8f5e8b4f5001f7a8c24",
  "60a7c8f5e8b4f5001f7a8c26",
  "60a7c8f5e8b4f5001f7a8c27"
]

status · enum<string>

Group status

Available options: Active, Inactive

Example:

"Active"

Response

200

application/json

Group updated successfully

success · boolean

Example:

true

message · string

Example:

"Group updated successfully"

group · object

Show child attributes