Safe AI Workbench Developer DocsAI-powered workspace with PHI protectionHIPAA-compliant API

Groups API

Manage user groups and control access to AI tasks and policies

Overview

The Groups API allows administrators to create and manage user groups within their organization. Groups can be assigned specific AI tasks, policies, and access controls, enabling fine-grained permission management and task sharing.

Use Cases

Create department-specific groups (HR, Finance, Operations)
Assign AI tasks to specific teams
Apply group-level policies for PHI handling
Control which users can access certain AI capabilities

List All Groups

GET /api/v1/groups

Returns all groups for the authenticated user's organization. Requires admin or manager role.

Request Headers

Authorization: Bearer YOUR_JWT_TOKEN

Response

{
  "groups": [
    {
      "id": "group-uuid-1",
      "name": "HR Department",
      "description": "Human Resources team",
      "isActive": true,
      "memberCount": 8,
      "assignedTasksCount": 5,
      "createdAt": "2025-01-10T09:00:00Z",
      "updatedAt": "2025-01-10T09:00:00Z"
    },
    {
      "id": "group-uuid-2",
      "name": "Finance Team",
      "description": "Finance and accounting",
      "isActive": true,
      "memberCount": 12,
      "assignedTasksCount": 7,
      "createdAt": "2025-01-10T09:15:00Z",
      "updatedAt": "2025-01-10T09:15:00Z"
    }
  ]
}

Get My Groups

GET /api/v1/groups/my-groups

Returns groups the authenticated user belongs to. No special permissions required.

Response

{
  "groups": [
    {
      "id": "group-uuid-1",
      "name": "HR Department",
      "description": "Human Resources team",
      "assignedAt": "2025-01-10T10:00:00Z"
    }
  ]
}

Create Group

POST /api/v1/groups

Creates a new group within your organization. Requires admin or manager role.

Request Body

{
  "name": "Marketing Team",
  "description": "Marketing and communications department",
  "isActive": true
}

Response

{
  "id": "new-group-uuid",
  "name": "Marketing Team",
  "description": "Marketing and communications department",
  "isActive": true,
  "memberCount": 0,
  "assignedTasksCount": 0,
  "createdAt": "2025-01-15T14:30:00Z",
  "updatedAt": "2025-01-15T14:30:00Z"
}

Get Group by ID

GET /api/v1/groups/:groupId

Returns detailed information about a specific group including members and assigned tasks.

Path Parameters

groupId— Group UUID

Response

{
  "id": "group-uuid",
  "name": "HR Department",
  "description": "Human Resources team",
  "isActive": true,
  "members": [
    {
      "userId": "user-uuid-1",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "assignedAt": "2025-01-10T10:00:00Z"
    }
  ],
  "assignedTasks": [
    {
      "taskId": "draft-email",
      "taskName": "Draft Email",
      "category": "HR & Communications",
      "assignedAt": "2025-01-10T09:30:00Z"
    }
  ],
  "createdAt": "2025-01-10T09:00:00Z",
  "updatedAt": "2025-01-10T09:00:00Z"
}

Add Group Members

POST /api/v1/groups/:groupId/members

Adds one or more users to a group. Requires admin or manager role.

Request Body

{
  "userIds": [
    "user-uuid-1",
    "user-uuid-2"
  ]
}

Response

{
  "message": "Members added successfully",
  "added": 2,
  "members": [
    {
      "userId": "user-uuid-1",
      "email": "john.doe@example.com",
      "name": "John Doe",
      "assignedAt": "2025-01-15T14:45:00Z"
    },
    {
      "userId": "user-uuid-2",
      "email": "jane.smith@example.com",
      "name": "Jane Smith",
      "assignedAt": "2025-01-15T14:45:00Z"
    }
  ]
}

Assign Tasks to Group

POST /api/v1/groups/:groupId/tasks

Assigns AI tasks to a group, making them available to all group members.

Request Body

{
  "taskIds": [
    "draft-email",
    "schedule-meeting",
    "performance-review"
  ]
}

Response

{
  "message": "Tasks assigned successfully",
  "assigned": 3,
  "tasks": [
    {
      "taskId": "draft-email",
      "taskName": "Draft Email",
      "category": "HR & Communications"
    },
    {
      "taskId": "schedule-meeting",
      "taskName": "Schedule Meeting",
      "category": "HR & Communications"
    },
    {
      "taskId": "performance-review",
      "taskName": "Performance Review",
      "category": "HR & Communications"
    }
  ]
}

Update Group

PUT /api/v1/groups/:groupId

Updates group properties such as name, description, or active status.

Request Body

{
  "name": "HR & Recruiting",
  "description": "Human Resources and Talent Acquisition",
  "isActive": true
}

Delete Group

DELETE /api/v1/groups/:groupId

Deletes a group. All member associations and task assignments are removed.

Response

{
  "message": "Group deleted successfully"
}

Error Codes

401 Unauthorized

Missing or invalid authentication token

403 Forbidden

Insufficient permissions (requires admin/manager role for most operations)

404 Not Found

Group not found or user not authorized to access it

400 Bad Request

Invalid group data or missing required fields

409 Conflict

Group name already exists in organization