Pawsitive Future Pawsitive FutureDeveloper docs

get_groups

Read-only

Calls GET /api/groups as the signed-in person · REST reference

List groups, scoped to the caller's organizations

Requires query:ListGroupsQuery; platform staff bypass that gate. BOUNDED BY THE CALLER'S ORG TREE — the organizations in which the caller holds admin.groups.view and every organization beneath them — for every caller, platform staff included; a caller holding it in no organization is refused 403. With orgId that org must be in the caller's tree (403 ORG_ACCESS_DENIED otherwise), and the caller gets that org's groups; without orgId, the groups of every org in the tree, fetched one org at a time. Another organization's groups are read by impersonating one of its people. ENVELOPE SHAPE — { success, data, singleOrgModel }, not the bare array that GET /api/users and /api/orgs/tree return. singleOrgModel is a constant true marker, not a computed property of the result. Rows are Group MODEL objects, not DAL entities: createdAt/updatedAt are ISO-8601 strings, type and status are defaulted when the entity omits them, and an organization: { id } stub is synthesised from orgId.

Arguments

ArgumentTypeDescription
orgIdquerystring (uuid)Must be a UUID when present, and an org in the caller's tree: one they hold admin.groups.view in, or an org beneath one.

Example call

A client sends this over the MCP session; Claude and other agents build it for you. The values are placeholders — the shape is real.

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_groups",
    "arguments": {}
  }
}

Result

On success (HTTP 200) the tool returns one text item holding the API's JSON, pretty-printed.

The visible groups, wrapped in the success envelope.

json
{
  "data": [
    {
      "createdAt": "2026-01-15T12:00:00Z",
      "id": "11111111-1111-4111-8111-111111111111",
      "memberCount": 1,
      "name": "string",
      "status": "ACTIVE",
      "type": "FUNCTIONAL",
      "allowFallthrough": true,
      "config": {},
      "createdBy": "11111111-1111-4111-8111-111111111111",
      "description": "string",
      "inviteOnly": true,
      "metadata": {},
      "orgId": "11111111-1111-4111-8111-111111111111",
      "organization": {}
    }
  ],
  "singleOrgModel": true,
  "success": true
}

Fields

FieldTypeDescription
dataarray of object
data[].allowFallthroughbooleanDefaults to true when the entity does not say otherwise.
data[].configobject
data[].createdAtstring (date-time)
data[].createdBystring (uuid) | null
data[].descriptionstring | null
data[].idstring (uuid)
data[].inviteOnlyboolean
data[].memberCountintegerProjected by the DAL, not stored on the node.
data[].metadataobject
data[].namestring
data[].orgIdstring (uuid) | null
data[].organizationobject | nullStub built from orgId: { id } and nothing else.
data[].organization.idstring (uuid)
data[].status"ACTIVE" | "INACTIVE" | "ARCHIVED"
data[].type"FUNCTIONAL" | "DEPARTMENTAL" | "ROLE_BASED" | "PROJECT" | "ADMIN" | "OWNER" | … (7 values)
data[].updatedAtstring (date-time)
singleOrgModeltrueConstant marker, always true.
successtrue

When it fails

A failed call returns isError: true with the API's message as text.

400

orgId was supplied and is not a UUID. Note the array-shaped details.

403

Missing query:ListGroupsQuery, no admin.groups.view in any org, or orgId names an org where the caller does not hold it — the last carries code: ORG_ACCESS_DENIED.

What the model is shown

This is the tool exactly as the server lists it in tools/list. The description starts with the REST call it makes.

json
{
  "name": "get_groups",
  "description": "GET /api/groups — Requires `query:ListGroupsQuery`; platform staff bypass that gate. BOUNDED BY THE CALLER'S ORG TREE — the organizations in which the caller holds `admin.groups.view` and every organization beneath them — for every caller, platform staff included; a caller holding it in no organization is refused 403. With `orgId` that org must be in the caller's tree (403 `ORG_ACCESS_DENIED` otherwise), and the caller gets that org's groups; without `orgId`, the groups of every org in the tree, fetched one org at a time. Another organization's groups are read by impersonating one of its people. ENVELOPE SHAPE — `{ success, data, singleOrgModel }`, not the bare array that `GET /api/users` and `/api/orgs/tree` return. `singleOrgModel` is a constant `true` marker, not a computed property of the result. Rows are `Group` MODEL objects, not DAL entities: `createdAt`/`updatedAt` are ISO-8601 strings, `type` and `status` are defaulted when the entity omits them, and an `organization: { id }` stub is synthesised from `orgId`.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "orgId": {
        "type": "string",
        "description": "Must be a UUID when present, and an org in the caller's tree: one they hold `admin.groups.view` in, or an org beneath one."
      }
    }
  },
  "annotations": {
    "readOnlyHint": true,
    "openWorldHint": false
  }
}