List Collaborator Groups

GET /siren/v1/collaborator-groups

Returns a paginated list of collaborator groups. Results are wrapped in a pagination envelope with items, total, page, perPage, and totalPages. All requests require authentication and the Read capability on the CollaboratorGroup resource.

The fields value selects from the registered group field resolvers. The core set is id, name, description, and structure, and a plugin can add more through the CollaboratorGroupResolverRegistryInitiated event. See Collaborator Groups (REST) for the full field reference. A name with no registered resolver is dropped from the response rather than returning an error.

Query Parameters:

Parameter	Type	Default	Description
fields	string	—	Comma-separated list of fields to include (required)
structure	string	—	Filter by structure resolver id, exact match. Values: flat, linearChain, parentChild
s	string	—	Search across name and description
number	integer	10	Results per page
offset	integer	0	Pagination offset
orderBy	string	id	Sort field
order	string	ASC	Sort direction: ASC or DESC

Response Headers:

• x-siren-estimated-count. Total matching records (exposed via Access-Control-Expose-Headers).

Example Request:

GET /siren/v1/collaborator-groups?fields=id,name,structure&s=sales

Example Response:

{
  "items": [
    {
      "id": 12,
      "name": "Sales Reps",
      "structure": "linearChain"
    }
  ],
  "total": 1,
  "page": 1,
  "perPage": 10,
  "totalPages": 1
}

Responds 200 with the resolved field set under items, alongside pagination metadata (total, page, perPage, totalPages). When no rows match, items is an empty array and total is 0. A datastore failure responds 500 with the message Something went wrong fetching collaborator group data.

The envelope is derived from your number and offset query parameters. perPage echoes number, page is floor(offset / number) + 1, and totalPages is ceil(total / number). The total is the same value carried in the x-siren-estimated-count response header, and totalPages is derived from it, so both are estimates rather than exact counts. Do not use either as a loop bound. To page through every group, hold number fixed, advance offset by number, and stop when a page returns fewer than number items.

Events: broadcasts CollaboratorGroupResolverRegistryInitiated so listeners can register additional field resolvers before the response is built.