> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helpgenie.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Genie groups

> Organize genies into groups for easier management

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.

<Note>
  Standard users can only manage their own groups. Admin users can manage groups for any user by passing a `userId`.
</Note>

***

## List groups

Retrieves all groups for the authenticated user.

<ParamField body="resource" type="string" required>
  Must be `"genie-groups"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"list"`
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="adminMode" type="boolean" default="false">
      Admin only. Enables cross-user access.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Target user whose groups to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="groups" type="array">
      <Expandable title="item properties">
        <ResponseField name="id" type="number">Group ID.</ResponseField>
        <ResponseField name="name" type="string">Group name.</ResponseField>
        <ResponseField name="description" type="string">Group description.</ResponseField>
        <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
        <ResponseField name="position" type="number">Display order position.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genie-groups", "list");
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "list"
  }
  ```

  ```json Response theme={null}
  {
    "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"
        }
      ]
    }
  }
  ```
</CodeGroup>

***

## Get group

Retrieves a single group by ID.

<ParamField body="resource" type="string" required>
  Must be `"genie-groups"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"get"`
</ParamField>

<ParamField body="id" type="string" required>
  The group ID to retrieve (passed as a string).
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="adminMode" type="boolean" default="false">
      Admin only. Enables cross-user access.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="group" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="number">Group ID.</ResponseField>
        <ResponseField name="name" type="string">Group name.</ResponseField>
        <ResponseField name="description" type="string">Group description.</ResponseField>
        <ResponseField name="user_id" type="string">Owner user ID.</ResponseField>
        <ResponseField name="position" type="number">Display order position.</ResponseField>
        <ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genie-groups", "get", "1");
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "get",
    "id": "1"
  }
  ```

  ```json Response theme={null}
  {
    "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"
      }
    }
  }
  ```
</CodeGroup>

***

## Create group

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

<ParamField body="resource" type="string" required>
  Must be `"genie-groups"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"create"`
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="name" type="string" required>
      Group display name.
    </ParamField>

    <ParamField body="description" type="string">
      A short description of the group's purpose.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Create the group for a specific user.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="group" type="object">
      The newly created group with all fields including auto-assigned `position`.
    </ResponseField>
  </Expandable>
</ResponseField>

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

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "create",
    "data": {
      "name": "Support Team",
      "description": "Genies for support workflows"
    }
  }
  ```

  ```json Response theme={null}
  {
    "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"
      }
    }
  }
  ```
</CodeGroup>

***

## Update group

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

<ParamField body="resource" type="string" required>
  Must be `"genie-groups"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"update"`
</ParamField>

<ParamField body="id" type="string" required>
  The group ID to update (passed as a string).
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="name" type="string">
      Updated group name.
    </ParamField>

    <ParamField body="description" type="string">
      Updated description.
    </ParamField>

    <ParamField body="position" type="number">
      Updated display position.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Target user who owns the group.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="group" type="object">
      The updated group with all current field values.
    </ResponseField>
  </Expandable>
</ResponseField>

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

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "update",
    "id": "1",
    "data": {
      "name": "Updated Sales Team",
      "description": "Updated description for sales genies",
      "position": 2
    }
  }
  ```

  ```json Response theme={null}
  {
    "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"
      }
    }
  }
  ```
</CodeGroup>

***

## Delete group

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

<ParamField body="resource" type="string" required>
  Must be `"genie-groups"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"delete"`
</ParamField>

<ParamField body="id" type="string" required>
  The group ID to delete (passed as a string).
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="userId" type="string">
      Admin only. Target user who owns the group.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean">Operation succeeded.</ResponseField>
    <ResponseField name="message" type="string">Confirmation message.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genie-groups", "delete", "1");
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "delete",
    "id": "1"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "message": "Group deleted successfully"
    }
  }
  ```
</CodeGroup>

***

## 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.

<ParamField body="resource" type="string" required>
  Must be `"genie-groups"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"reorder"`
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="groupIds" type="number[]" required>
      Ordered array of group IDs. The first ID gets position 0, the second gets position 1, and so on.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Target user whose groups to reorder.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="success" type="boolean">Operation succeeded.</ResponseField>
    <ResponseField name="message" type="string">Confirmation message.</ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke(
    "genie-groups",
    "reorder",
    undefined,
    {
      groupIds: [1, 3, 2],
    }
  );
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "reorder",
    "data": {
      "groupIds": [1, 3, 2]
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "success": true,
      "message": "Groups reordered successfully"
    }
  }
  ```
</CodeGroup>

***

## Get group genie counts

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

<ParamField body="resource" type="string" required>
  Must be `"genie-groups"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"counts"`
</ParamField>

<ParamField body="data" type="object">
  <Expandable title="properties">
    <ParamField body="adminMode" type="boolean" default="false">
      Admin only. Enables cross-user access.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Target user whose group counts to retrieve.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="counts" type="object">
      An object where keys are group IDs (as strings) and values are genie counts.
    </ResponseField>
  </Expandable>
</ResponseField>

<CodeGroup>
  ```typescript ApiService.invoke() theme={null}
  const response = await ApiService.invoke("genie-groups", "counts");
  ```

  ```json Request body theme={null}
  {
    "resource": "genie-groups",
    "action": "counts"
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "counts": {
        "1": 5,
        "2": 2
      }
    }
  }
  ```
</CodeGroup>

***

## 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.

<ParamField body="resource" type="string" required>
  Must be `"genie-groups"`
</ParamField>

<ParamField body="action" type="string" required>
  Must be `"sync"`
</ParamField>

<ParamField body="data" type="object" required>
  <Expandable title="properties">
    <ParamField body="agentId" type="string" required>
      The genie ID to assign or unassign.
    </ParamField>

    <ParamField body="groupId" type="number | null" required>
      The group ID to assign the genie to, or `null` to remove the genie from its group.
    </ParamField>

    <ParamField body="userId" type="string">
      Admin only. Target user who owns the genie.
    </ParamField>
  </Expandable>
</ParamField>

<ResponseField name="success" type="boolean">
  Whether the request succeeded.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="properties">
    <ResponseField name="agent" type="object">
      <Expandable title="properties">
        <ResponseField name="id" type="string">Genie ID.</ResponseField>
        <ResponseField name="group_id" type="number | null">The new group ID, or `null` if unassigned.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="previousGroupId" type="number | null">
      The group ID the genie was previously in.
    </ResponseField>

    <ResponseField name="newGroupId" type="number | null">
      The group ID the genie is now in.
    </ResponseField>
  </Expandable>
</ResponseField>

<Tip>
  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`.
</Tip>

<CodeGroup>
  ```typescript ApiService.invoke() theme={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,
    }
  );
  ```

  ```bash cURL (assign to group) theme={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
      }
    }'
  ```

  ```bash cURL (remove from group) theme={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": null
      }
    }'
  ```

  ```json Request body (assign) theme={null}
  {
    "resource": "genie-groups",
    "action": "sync",
    "data": {
      "agentId": "550e8400-e29b-41d4-a716-446655440000",
      "groupId": 2
    }
  }
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "agent": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "group_id": 2
      },
      "previousGroupId": 1,
      "newGroupId": 2
    }
  }
  ```
</CodeGroup>

***

## 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                                             |