Skip to content

Groups API

The GroupsAPI client exposes three read endpoints added in v0.5.0.

Resource grouping

All endpoints are grouped under client.groups (D-v0.5-1), separate from PostsAPI or other resource clients.

Usage

from pynteracta.client import InteractaClient

with InteractaClient(base_url="https://tenant.example.com", credentials=...) as client:
    # List groups (first page)
    page = client.groups.list_groups()
    for g in page.items_typed:
        print(g.id, g.name, g.members_count)

    # Iterate all pages lazily
    for g in client.groups.iterate_groups(full_text_filter="eng"):
        print(g.id, g.name)

    # List members of a group
    members = client.groups.list_members(201)
    for m in members.members_typed:
        print(m.id, m.full_name, m.email)

    # Iterate all member pages
    for m in client.groups.iterate_members(201, page_size=50):
        print(m.id, m.full_name)

    # Fetch group detail (for-edit form; includes members list and occToken)
    group = client.groups.get_for_edit(201)
    print(group.name, group.members_count)
    print(group.raw.occToken)  # occToken only on .raw — for future write use

Sort fields for list_groups

The API uses orderTypeId (not orderBy). Valid values: 'name', 'email'. Pass as order_type_id kwarg; order_desc controls direction.

API Reference

pynteracta.api.groups.GroupsAPI

Bases: ResourceClient

Client for group listing, member listing, and group-for-edit endpoints.

list_groups(*, page_token=None, page_size=None, full_text_filter=None, status_filter=None, workspace_ids=None, order_type_id=None, order_desc=None)

POST /admin/data/groups.

Parameters:

Name Type Description Default
page_token str | None

Pagination cursor from a previous response.

 None
page_size int | None

Maximum items per page.

 None
full_text_filter str | None

Full-text filter on group name and email.

 None
status_filter list[int] | None

Filter by group status codes.

 None
workspace_ids list[int] | None

Filter by workspace IDs.

 None
order_type_id str | None

Sort field. Valid values: 'name', 'email'.

 None
order_desc bool | None

True for descending, False for ascending (default: True).

 None

list_groups_raw(req)

POST group list with a pre-built request DTO (escape hatch).

iterate_groups(*, page_size=None, full_text_filter=None, status_filter=None, workspace_ids=None, order_type_id=None, order_desc=None)

Lazy iterator over all pages of :meth:list_groups.

list_members(group_id, *, page_token=None, page_size=None)

POST /admin/data/groups/{groupId}/members.

Parameters:

Name Type Description Default
group_id int

The group whose members to list.

 required
page_token str | None

Pagination cursor.

 None
page_size int | None

Maximum items per page.

 None

iterate_members(group_id, *, page_size=None)

Lazy iterator over all pages of :meth:list_members.

get_for_edit(group_id)

GET /admin/manage/groups/{groupId}/edit.

Parameters:

Name Type Description Default
group_id int

The group ID to fetch.

 required

Facade Reference

pynteracta.models.facade.groups.Group

Narrow facade over :class:~generated.ListSystemGroupsElementDTOModel.

ListSystemGroupsResponseDTO.items are typed as ListSystemGroupsElementDTO (RootModel[Any] stubs); bind to the typed ListSystemGroupsElementDTOModel.

Attributes:

Name Type Description
raw

The underlying typed DTO; access additional fields via this escape hatch.
Source code in src/pynteracta/models/facade/groups.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
class Group:
    """Narrow facade over :class:`~generated.ListSystemGroupsElementDTOModel`.

    ``ListSystemGroupsResponseDTO.items`` are typed as ``ListSystemGroupsElementDTO``
    (``RootModel[Any]`` stubs); bind to the typed ``ListSystemGroupsElementDTOModel``.

    Attributes:
        raw: The underlying typed DTO; access additional fields via this escape hatch.
    """

    def __init__(self, raw: generated.ListSystemGroupsElementDTOModel) -> None:
        self.raw = raw

    @property
    def id(self) -> int | None:
        return self.raw.id

    @property
    def name(self) -> str | None:
        return self.raw.name

    @property
    def email(self) -> str | None:
        return self.raw.email

    @property
    def description(self) -> str | None:
        return self.raw.description

    @property
    def members_count(self) -> int | None:
        return self.raw.membersCount

    @property
    def visible(self) -> bool | None:
        return self.raw.visible

    @property
    def deleted(self) -> bool | None:
        return self.raw.deleted

    @property
    def creation_timestamp(self) -> int | None:
        return self.raw.creationTimestamp

    @property
    def tags_typed(self) -> list[Tag]:
        """Re-validate each opaque ``TagDTO`` stub into :class:`Tag`."""
        if not self.raw.tags:
            return []
        result = []
        for t in self.raw.tags:
            root = _resolve_root(t)
            if isinstance(root, dict):
                result.append(Tag(generated.TagDTO1.model_validate(root)))
        return result

    @classmethod
    def from_dict(cls, data: dict) -> Group:  # type: ignore[type-arg]
        """Parse from a raw dict item."""
        raw = generated.ListSystemGroupsElementDTOModel.model_validate(data)
        return cls(raw)

tags_typed property

Re-validate each opaque TagDTO stub into :class:Tag.

from_dict(data) classmethod

Parse from a raw dict item.

Source code in src/pynteracta/models/facade/groups.py 
147
148
149
150
151
@classmethod
def from_dict(cls, data: dict) -> Group:  # type: ignore[type-arg]
    """Parse from a raw dict item."""
    raw = generated.ListSystemGroupsElementDTOModel.model_validate(data)
    return cls(raw)

pynteracta.models.facade.groups.GroupList

Narrow facade over :class:~generated.ListSystemGroupsResponseDTO.

items are ListSystemGroupsElementDTO (RootModel[Any] stubs); call :meth:items_typed to get :class:Group instances.

Attributes:

Name Type Description
raw

The underlying generated DTO; access additional fields via this escape hatch.
Source code in src/pynteracta/models/facade/groups.py 
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
class GroupList:
    """Narrow facade over :class:`~generated.ListSystemGroupsResponseDTO`.

    ``items`` are ``ListSystemGroupsElementDTO`` (``RootModel[Any]`` stubs); call
    :meth:`items_typed` to get :class:`Group` instances.

    Attributes:
        raw: The underlying generated DTO; access additional fields via this escape hatch.
    """

    def __init__(self, raw: generated.ListSystemGroupsResponseDTO) -> None:
        self.raw = raw

    @property
    def next_page_token(self) -> str | None:
        return self.raw.nextPageToken

    @property
    def total_items_count(self) -> int | None:
        return self.raw.totalItemsCount

    @property
    def items_typed(self) -> list[Group]:
        """Re-validate each opaque list item into :class:`Group`."""
        if not self.raw.items:
            return []
        result = []
        for item in self.raw.items:
            root = _resolve_root(item)
            if isinstance(root, dict):
                result.append(Group(generated.ListSystemGroupsElementDTOModel.model_validate(root)))
        return result

    @classmethod
    def from_dict(cls, data: dict) -> GroupList:  # type: ignore[type-arg]
        """Parse from a raw API response dict."""
        raw = generated.ListSystemGroupsResponseDTO.model_validate(data)
        return cls(raw)

items_typed property

Re-validate each opaque list item into :class:Group.

from_dict(data) classmethod

Parse from a raw API response dict.

Source code in src/pynteracta/models/facade/groups.py 
187
188
189
190
191
@classmethod
def from_dict(cls, data: dict) -> GroupList:  # type: ignore[type-arg]
    """Parse from a raw API response dict."""
    raw = generated.ListSystemGroupsResponseDTO.model_validate(data)
    return cls(raw)

pynteracta.models.facade.groups.GroupMember

Thin facade over :class:~generated.UserDTOModel for a group member.

ListGroupMembersResponseDTO.items and GetGroupForEditResponseDTO.members are typed as list[UserDTO] (RootModel[Any] stubs); this facade wraps the re-validated typed sibling.

Attributes:

Name Type Description
raw

The underlying typed DTO.
Source code in src/pynteracta/models/facade/groups.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
class GroupMember:
    """Thin facade over :class:`~generated.UserDTOModel` for a group member.

    ``ListGroupMembersResponseDTO.items`` and ``GetGroupForEditResponseDTO.members`` are typed as
    ``list[UserDTO]`` (``RootModel[Any]`` stubs); this facade wraps the re-validated typed sibling.

    Attributes:
        raw: The underlying typed DTO.
    """

    def __init__(self, raw: generated.UserDTOModel) -> None:
        self.raw = raw

    @property
    def id(self) -> int | None:
        return self.raw.id

    @property
    def first_name(self) -> str | None:
        return self.raw.firstName

    @property
    def last_name(self) -> str | None:
        return self.raw.lastName

    @property
    def full_name(self) -> str | None:
        parts = [p for p in (self.raw.firstName, self.raw.lastName) if p]
        return " ".join(parts) if parts else None

    @property
    def email(self) -> str | None:
        return self.raw.contactEmail

    @property
    def deleted(self) -> bool | None:
        return self.raw.deleted

    @property
    def blocked(self) -> bool | None:
        return self.raw.blocked

    @classmethod
    def from_stub(cls, stub: generated.UserDTO) -> GroupMember:
        """Re-validate a ``UserDTO`` ``RootModel[Any]`` stub into :class:`GroupMember`."""
        root = _resolve_root(stub)
        if isinstance(root, dict):
            return cls(generated.UserDTOModel.model_validate(root))
        msg = f"Unexpected stub root type: {type(root)}"
        raise ValueError(msg)

from_stub(stub) classmethod

Re-validate a UserDTO RootModel[Any] stub into :class:GroupMember.

Source code in src/pynteracta/models/facade/groups.py 
80
81
82
83
84
85
86
87
@classmethod
def from_stub(cls, stub: generated.UserDTO) -> GroupMember:
    """Re-validate a ``UserDTO`` ``RootModel[Any]`` stub into :class:`GroupMember`."""
    root = _resolve_root(stub)
    if isinstance(root, dict):
        return cls(generated.UserDTOModel.model_validate(root))
    msg = f"Unexpected stub root type: {type(root)}"
    raise ValueError(msg)

pynteracta.models.facade.groups.GroupMemberList

Narrow facade over :class:~generated.ListGroupMembersResponseDTO.

Attributes:

Name Type Description
raw

The underlying generated DTO; access additional fields via this escape hatch.
Source code in src/pynteracta/models/facade/groups.py 
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
class GroupMemberList:
    """Narrow facade over :class:`~generated.ListGroupMembersResponseDTO`.

    Attributes:
        raw: The underlying generated DTO; access additional fields via this escape hatch.
    """

    def __init__(self, raw: generated.ListGroupMembersResponseDTO) -> None:
        self.raw = raw

    @property
    def next_page_token(self) -> str | None:
        return self.raw.nextPageToken

    @property
    def total_items_count(self) -> int | None:
        return self.raw.totalItemsCount

    @property
    def members_typed(self) -> list[GroupMember]:
        """Re-validate each opaque ``UserDTO`` stub into :class:`GroupMember`."""
        if not self.raw.items:
            return []
        result = []
        for item in self.raw.items:
            root = _resolve_root(item)
            if isinstance(root, dict):
                result.append(GroupMember(generated.UserDTOModel.model_validate(root)))
        return result

    @classmethod
    def from_dict(cls, data: dict) -> GroupMemberList:  # type: ignore[type-arg]
        """Parse from a raw API response dict."""
        raw = generated.ListGroupMembersResponseDTO.model_validate(data)
        return cls(raw)

members_typed property

Re-validate each opaque UserDTO stub into :class:GroupMember.

from_dict(data) classmethod

Parse from a raw API response dict.

Source code in src/pynteracta/models/facade/groups.py 
224
225
226
227
228
@classmethod
def from_dict(cls, data: dict) -> GroupMemberList:  # type: ignore[type-arg]
    """Parse from a raw API response dict."""
    raw = generated.ListGroupMembersResponseDTO.model_validate(data)
    return cls(raw)

pynteracta.models.facade.groups.GroupForEdit

Narrow facade over :class:~generated.GetGroupForEditResponseDTO.

The members list contains UserDTO (RootModel[Any] stubs); call :meth:members_typed to re-validate them. occToken is only on .raw — it is the propaedeutic edit token for the future write surface.

Attributes:

Name Type Description
raw

The underlying generated DTO; access additional fields via this escape hatch.
Source code in src/pynteracta/models/facade/groups.py 
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
class GroupForEdit:
    """Narrow facade over :class:`~generated.GetGroupForEditResponseDTO`.

    The ``members`` list contains ``UserDTO`` (``RootModel[Any]`` stubs); call
    :meth:`members_typed` to re-validate them. ``occToken`` is only on ``.raw`` — it is the
    propaedeutic edit token for the future write surface.

    Attributes:
        raw: The underlying generated DTO; access additional fields via this escape hatch.
    """

    def __init__(self, raw: generated.GetGroupForEditResponseDTO) -> None:
        self.raw = raw

    @property
    def id(self) -> int | None:
        return self.raw.id

    @property
    def name(self) -> str | None:
        return self.raw.name

    @property
    def email(self) -> str | None:
        return self.raw.email

    @property
    def description(self) -> str | None:
        return self.raw.description

    @property
    def members_count(self) -> int | None:
        return self.raw.membersCount

    @property
    def visible(self) -> bool | None:
        return self.raw.visible

    @property
    def deleted(self) -> bool | None:
        return self.raw.deleted

    @property
    def creation_timestamp(self) -> int | None:
        return self.raw.creationTimestamp

    @property
    def tags_typed(self) -> list[Tag]:
        """Re-validate each opaque ``TagDTO`` stub into :class:`Tag`."""
        if not self.raw.tags:
            return []
        result = []
        for t in self.raw.tags:
            root = _resolve_root(t)
            if isinstance(root, dict):
                result.append(Tag(generated.TagDTO1.model_validate(root)))
        return result

    @property
    def members_typed(self) -> list[GroupMember]:
        """Re-validate each opaque ``UserDTO`` stub into :class:`GroupMember`."""
        if not self.raw.members:
            return []
        result = []
        for item in self.raw.members:
            root = _resolve_root(item)
            if isinstance(root, dict):
                result.append(GroupMember(generated.UserDTOModel.model_validate(root)))
        return result

    @classmethod
    def from_dict(cls, data: dict) -> GroupForEdit:  # type: ignore[type-arg]
        """Parse from a raw API response dict."""
        raw = generated.GetGroupForEditResponseDTO.model_validate(data)
        return cls(raw)

members_typed property

Re-validate each opaque UserDTO stub into :class:GroupMember.

tags_typed property

Re-validate each opaque TagDTO stub into :class:Tag.

from_dict(data) classmethod

Parse from a raw API response dict.

Source code in src/pynteracta/models/facade/groups.py 
301
302
303
304
305
@classmethod
def from_dict(cls, data: dict) -> GroupForEdit:  # type: ignore[type-arg]
    """Parse from a raw API response dict."""
    raw = generated.GetGroupForEditResponseDTO.model_validate(data)
    return cls(raw)

pynteracta.models.facade.groups.Tag

Thin facade over :class:~generated.TagDTO1.

Attributes:

Name Type Description
raw

The underlying typed DTO.
Source code in src/pynteracta/models/facade/groups.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
class Tag:
    """Thin facade over :class:`~generated.TagDTO1`.

    Attributes:
        raw: The underlying typed DTO.
    """

    def __init__(self, raw: generated.TagDTO1) -> None:
        self.raw = raw

    @property
    def id(self) -> int | None:
        return self.raw.id

    @property
    def name(self) -> str | None:
        return self.raw.name

    @property
    def visible(self) -> bool | None:
        return self.raw.visible