Genie groups

Genie groups let you organize your genies into logical categories such as “Sales Team” or “Support Team”. Each group has a name, optional description, and a position for display ordering. Genies can be assigned to a group via the sync action.

Standard users can only manage their own groups. Admin users can manage groups for any user by passing a userId.

List groups

Retrieves all groups for the authenticated user.

string

required

Must be "genie-groups"

string

required

Must be "list"

object

Show properties

boolean

default:"false"

Admin only. Enables cross-user access.

string

Admin only. Target user whose groups to retrieve.

boolean

Whether the request succeeded.

object

Show properties

array

Show item properties

number

Group ID.

string

Group name.

string

Group description.

string

Owner user ID.

number

Display order position.

string

ISO 8601 creation timestamp.

const response = await ApiService.invoke("genie-groups", "list");

{
  "resource": "genie-groups",
  "action": "list"
}

{
  "success": true,
  "data": {
    "groups": [
      {
        "id": 1,
        "name": "Sales Team",
        "description": "Genies for sales workflows",
        "user_id": "user_123",
        "position": 0,
        "created_at": "2026-02-19T10:00:00.000Z"
      }
    ]
  }
}

Get group

Retrieves a single group by ID.

string

required

Must be "genie-groups"

string

required

Must be "get"

string

required

The group ID to retrieve (passed as a string).

object

Show properties

boolean

default:"false"

Admin only. Enables cross-user access.

boolean

Whether the request succeeded.

object

Show properties

object

Show properties

number

Group ID.

string

Group name.

string

Group description.

string

Owner user ID.

number

Display order position.

string

ISO 8601 creation timestamp.

const response = await ApiService.invoke("genie-groups", "get", "1");

{
  "resource": "genie-groups",
  "action": "get",
  "id": "1"
}

{
  "success": true,
  "data": {
    "group": {
      "id": 1,
      "name": "Sales Team",
      "description": "Genies for sales workflows",
      "user_id": "user_123",
      "position": 0,
      "created_at": "2026-02-19T10:00:00.000Z"
    }
  }
}

Create group

Creates a new genie group. The group is automatically assigned the next available position.

string

required

Must be "genie-groups"

string

required

Must be "create"

object

required

Show properties

string

required

Group display name.

string

A short description of the group’s purpose.

string

Admin only. Create the group for a specific user.

boolean

Whether the request succeeded.

object

Show properties

object

The newly created group with all fields including auto-assigned position.

const response = await ApiService.invoke(
  "genie-groups",
  "create",
  undefined,
  {
    name: "Support Team",
    description: "Genies for support workflows",
  }
);

{
  "resource": "genie-groups",
  "action": "create",
  "data": {
    "name": "Support Team",
    "description": "Genies for support workflows"
  }
}

{
  "success": true,
  "data": {
    "group": {
      "id": 2,
      "name": "Support Team",
      "description": "Genies for support workflows",
      "user_id": "user_123",
      "position": 1,
      "created_at": "2026-02-19T10:05:00.000Z"
    }
  }
}

Update group

Updates an existing group’s properties. Only the fields you provide are changed.

string

required

Must be "genie-groups"

string

required

Must be "update"

string

required

The group ID to update (passed as a string).

object

required

Show properties

string

Updated group name.

string

Updated description.

number

Updated display position.

string

Admin only. Target user who owns the group.

boolean

Whether the request succeeded.

object

Show properties

object

The updated group with all current field values.

const response = await ApiService.invoke("genie-groups", "update", "1", {
  name: "Updated Sales Team",
  description: "Updated description for sales genies",
  position: 2,
});

{
  "resource": "genie-groups",
  "action": "update",
  "id": "1",
  "data": {
    "name": "Updated Sales Team",
    "description": "Updated description for sales genies",
    "position": 2
  }
}

{
  "success": true,
  "data": {
    "group": {
      "id": 1,
      "name": "Updated Sales Team",
      "description": "Updated description for sales genies",
      "user_id": "user_123",
      "position": 2,
      "created_at": "2026-02-19T10:00:00.000Z"
    }
  }
}

Delete group

Permanently deletes a group. Genies in the group are not deleted; their group_id is set to null.

string

required

Must be "genie-groups"

string

required

Must be "delete"

string

required

The group ID to delete (passed as a string).

object

Show properties

string

Admin only. Target user who owns the group.

boolean

Whether the request succeeded.

object

Show properties

boolean

Operation succeeded.

string

Confirmation message.

const response = await ApiService.invoke("genie-groups", "delete", "1");

{
  "resource": "genie-groups",
  "action": "delete",
  "id": "1"
}

{
  "success": true,
  "data": {
    "success": true,
    "message": "Group deleted successfully"
  }
}

Reorder groups

Updates the display order of groups based on an ordered array of group IDs. The position of each group is set to its index in the array.

string

required

Must be "genie-groups"

string

required

Must be "reorder"

object

required

Show properties

number[]

required

Ordered array of group IDs. The first ID gets position 0, the second gets position 1, and so on.

string

Admin only. Target user whose groups to reorder.

boolean

Whether the request succeeded.

object

Show properties

boolean

Operation succeeded.

string

Confirmation message.

const response = await ApiService.invoke(
  "genie-groups",
  "reorder",
  undefined,
  {
    groupIds: [1, 3, 2],
  }
);

{
  "resource": "genie-groups",
  "action": "reorder",
  "data": {
    "groupIds": [1, 3, 2]
  }
}

{
  "success": true,
  "data": {
    "success": true,
    "message": "Groups reordered successfully"
  }
}

Get group genie counts

Returns the number of genies in each group. Useful for displaying counts in group lists without fetching all genies.

string

required

Must be "genie-groups"

string

required

Must be "counts"

object

Show properties

boolean

default:"false"

Admin only. Enables cross-user access.

string

Admin only. Target user whose group counts to retrieve.

boolean

Whether the request succeeded.

object

Show properties

object

An object where keys are group IDs (as strings) and values are genie counts.

const response = await ApiService.invoke("genie-groups", "counts");

{
  "resource": "genie-groups",
  "action": "counts"
}

{
  "success": true,
  "data": {
    "counts": {
      "1": 5,
      "2": 2
    }
  }
}

Sync genie to group

Assigns or clears a group for a specific genie. Pass a groupId to assign the genie to a group, or pass null to remove the genie from its current group.

string

required

Must be "genie-groups"

string

required

Must be "sync"

object

required

Show properties

string

required

The genie ID to assign or unassign.

number | null

required

The group ID to assign the genie to, or null to remove the genie from its group.

string

Admin only. Target user who owns the genie.

boolean

Whether the request succeeded.

object

Show properties

object

Show properties

string

Genie ID.

number | null

The new group ID, or null if unassigned.

number | null

The group ID the genie was previously in.

number | null

The group ID the genie is now in.

Use the sync action to move a genie between groups. To transfer a genie from one group to another, simply pass the new groupId — the genie is automatically removed from its previous group. To remove a genie from all groups without assigning a new one, pass groupId: null.

// Assign a genie to a group
const response = await ApiService.invoke(
  "genie-groups",
  "sync",
  undefined,
  {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    groupId: 2,
  }
);

// Remove a genie from its group
const response = await ApiService.invoke(
  "genie-groups",
  "sync",
  undefined,
  {
    agentId: "550e8400-e29b-41d4-a716-446655440000",
    groupId: null,
  }
);

curl -X POST https://api.helpgenie.ai/v1/genie-groups \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "groupId": 2
    }
  }'

curl -X POST https://api.helpgenie.ai/v1/genie-groups \
  -H "Authorization: Bearer hg_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sync",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "groupId": null
    }
  }'

{
  "resource": "genie-groups",
  "action": "sync",
  "data": {
    "agentId": "550e8400-e29b-41d4-a716-446655440000",
    "groupId": 2
  }
}

{
  "success": true,
  "data": {
    "agent": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "group_id": 2
    },
    "previousGroupId": 1,
    "newGroupId": 2
  }
}

Error codes

Code	Status	Description
`UNAUTHORIZED`	401	Missing or invalid authentication token
`FORBIDDEN`	403	Only admins can manage groups for other users
`NOT_FOUND`	404	Group not found
`VALIDATION_ERROR`	400	Missing or invalid parameters (for example group ID required)
`INTERNAL_ERROR`	500	Server-side error

Overview

Public (unauthenticated)

Agents

Knowledge

CRM

Marketplace

Platform

Telephony

Worker genies

Quality & Compliance

Access Control

Intelligence

Education

Voice

Integrations

Expanded Platform

List groups

Get group

Create group

Update group

Delete group

Reorder groups

Get group genie counts

Sync genie to group

Error codes

​List groups

​Get group

​Create group

​Update group

​Delete group

​Reorder groups

​Get group genie counts

​Sync genie to group

​Error codes

List groups

Get group

Create group

Update group

Delete group

Reorder groups

Get group genie counts

Sync genie to group

Error codes