---
myst:
  html_meta:
    "description": "Available groups in a Plone site can be created, queried, updated, and deleted by interacting with the /@groups endpoint on the portal root."
    "property=og:description": "Available groups in a Plone site can be created, queried, updated, and deleted by interacting with the /@groups endpoint on the portal root."
    "property=og:title": "Groups"
    "keywords": "Plone, plone.restapi, REST, API, Groups"
---

# Groups

Available groups in a Plone site can be created, queried, updated, and deleted by interacting with the `/@groups` endpoint on the portal root.
This requires an authenticated user.


## List Groups

To retrieve a list of all current groups in the portal, call the `/@groups` endpoint with a `GET` request:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/groups.req
```

The server will respond with a list of all groups in the portal:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/groups.resp
:language: http
```

The endpoint supports some basic filtering:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/groups_filtered_by_groupname.req
```

The server will respond with a list of the filtered groups in the portal where `groupname` starts with the value of the `query` parameter.

The endpoint also takes a `limit` parameter.
Its default is a maximum of 25 groups at a time for performance reasons:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/groups_filtered_by_groupname.resp
:language: http
```


## Create Group

To create a new group, send a `POST` request to the global `/@groups` endpoint with a JSON representation of the group you want to create in the body:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/groups_created.req
```

```{note}
By default, `groupname` is a required field.
```

If the group has been created successfully, the server will respond with a status {term}`201 Created`. The `Location` header contains the URL of the newly created group, and the resource representation is in the payload:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/groups_created.resp
:language: http
```


## Read Group

To retrieve all details for a particular group, send a `GET` request to the `/@groups` endpoint and append the group ID to the URL:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/groups_get.req
```

The server will respond with a {term}`200 OK` status code and the JSON representation of the group in the body:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/groups_get.resp
:language: http
```

Batching is supported for the `users` object.


## Update Group

To update the settings of a group, send a `PATCH` request with the group details you want to amend to the URL of that particular group:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/groups_update.req
```

```{note}
The `users` object is a mapping of a `user_id` and a boolean indicating adding or removing from the group.
```

A successful response to a `PATCH` request will be indicated by a {term}`204 No Content` response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/groups_update.resp
:language: http
```


## Delete Group

To delete a group, send a `DELETE` request to the `/@groups` endpoint and append the group id of the group you want to delete:

```{eval-rst}
..  http:example:: curl httpie python-requests
    :request: ../../../src/plone/restapi/tests/http-examples/groups_delete.req
```

A successful response will be indicated by a {term}`204 No Content` response:

```{literalinclude} ../../../src/plone/restapi/tests/http-examples/groups_delete.resp
:language: js
```