API: Groups
Groups are collections of users. They support assigning/unassigning multiple users to/from a project in one operation.
This resource does not yet have the form and schema endpoints. But as all properties are static, clients should still be able to work with this resource.
Actions
Actions
| Link | Description | Condition |
|---|---|---|
| delete | Deletes the group. | Permission: Administrator |
| updateImmediately | Updates the group’s attributes. | Permission: Administrator |
Linked Properties
| Link | Description | Type | Constraints | Supported operations | Condition |
|---|---|---|---|---|---|
| self | This group | Group | not null | READ | |
| memberships | Link to collection of all the group’s memberships. The list will only include the memberships in projects in which the requesting user has the necessary permissions. | MemberCollection | READ | Permission: view members or manage members in any project | |
| members | The list all all the users that are members of the group | UserCollection | READ/WRITE | Permission: manage members in any project to read & admin to write |
Local Properties
| Property | Description | Type | Constraints | Supported operations | Condition |
|---|---|---|---|---|---|
| id | Group’s id | Integer | x > 0 | READ | |
| name | Group’s full name, formatting depends on instance settings | String | READ/WRITE | Admin to write | |
| createdAt | Time of creation | DateTime | READ | Only visible by admins | |
| updatedAt | Time of the most recent change to the user | DateTime | READ | Only visible by admins |
Methods
List groups
Returns a collection of groups. The client can choose to filter the groups similar to how work packages are filtered. In addition to the provided filters, the server will reduce the result set to only contain groups, for which the requesting client has sufficient permissions (view_members, manage_members).
sortBy
string
optional query
JSON specifying sort criteria. Accepts the same format as returned by the queries endpoint. Currently supported sorts are:
-
id: Sort by primary key
-
created_at: Sort by group creation datetime
-
updated_at: Sort by the time the group was updated last
Default:[["id", "asc"]]
Example:[["id", "asc"]]
select
string
optional query
Comma separated list of properties to include.
Example:total,elements/name,elements/self,self
200
OK
GroupCollectionModel{
"allOf": [
{
"$ref": "#/components/schemas/CollectionModel"
},
{
"type": "object",
"required": [
"_links",
"_embedded"
],
"properties": {
"_links": {
"type": "object",
"required": [
"self"
],
"properties": {
"self": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "This group collection\n\n**Resource**: Collection"
}
]
}
}
},
"_embedded": {
"type": "object",
"required": [
"elements"
],
"properties": {
"elements": {
"type": "array",
"items": {
"$ref": "#/components/schemas/GroupModel"
}
}
}
}
}
}
],
"example": {
"_type": "Collection",
"total": 2,
"count": 2,
"_links": {
"self": {
"href": "/api/v3/groups"
}
},
"_embedded": {
"elements": [
{
"_type": "Group",
"id": 1337,
"name": "Stormtroopers",
"createdAt": "2022-09-23T11:06:36.300Z",
"updatedAt": "2022-09-23T11:06:36.300Z",
"_links": {
"self": {
"href": "/api/v3/groups/9",
"title": "Stormtroopers"
},
"delete": {
"href": "/api/v3/group/9",
"method": "delete"
},
"memberships": {
"href": "/api/v3/memberships?filters=[{\"principal\":{\"operator\":\"=\",\"values\":[\"9\"]}}]",
"title": "Memberships"
},
"updateImmediately": {
"href": "/api/v3/group/9",
"method": "patch"
},
"members": [
{
"href": "/api/v3/users/363",
"title": "ST-097E"
},
{
"href": "/api/v3/users/60",
"title": "ST-C-334"
}
]
}
},
{
"_hint": "Group resource shortened for brevity",
"id": 1338
}
]
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: View members or manage members in any project
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Create group
Creates a new group applying the attributes provided in the body.
No parameters
201
Created
GroupModel{
"allOf": [
{
"$ref": "#/components/schemas/PrincipalModel"
},
{
"type": "object",
"required": [
"_type",
"_embedded"
],
"properties": {
"_type": {
"type": "string",
"enum": [
"Group"
]
},
"_embedded": {
"type": "object",
"properties": {
"members": {
"type": "array",
"description": "Embedded list of members.",
"items": [
{
"$ref": "#/components/schemas/UserModel"
}
]
}
}
},
"_links": {
"type": "object",
"properties": {
"members": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "A member of the group\n\n# Conditions:\n\n- user has permission `manage_members` in any project\n\n**Resource**: User"
}
]
}
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "An href to delete the group.\n\n# Conditions:\n\n- `admin`"
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "An href to update the group.\n\n# Conditions:\n\n- `admin`\n\n**Resource**: Group"
}
]
}
}
}
}
}
]
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: Administrator
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation)
{
"_embedded": {
"details": {
"attribute": "name"
}
},
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Name can't be blank."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Get group
Fetches a group resource.
id
integer
required path
Group id
Example:1
200
OK
{
"_type": "Group",
"id": 26,
"name": "Force Users",
"createdAt": "2024-01-11T15:54:16.542Z",
"updatedAt": "2024-01-11T15:58:02.237Z",
"_embedded": {
"members": [
{
"_hint": "Principal resource shortened for brevity",
"_type": "User",
"id": 23,
"name": "Grogu Jarin"
},
{
"_hint": "Principal resource shortened for brevity",
"_type": "User",
"id": 14,
"name": "Mara Jade"
},
{
"_hint": "Principal resource shortened for brevity",
"_type": "User",
"id": 3,
"name": "Darth Vader"
}
]
},
"_links": {
"self": {
"href": "/api/v3/groups/26",
"title": "Force Users"
},
"memberships": {
"href": "/api/v3/memberships?filters=%5B%7B%22principal%22%3A%7B%22operator%22%3A%22%3D%22%2C%22values%22%3A%5B%2226%22%5D%7D%7D%5D",
"title": "Memberships"
},
"delete": {
"href": "/api/v3/groups/26",
"method": "delete"
},
"updateImmediately": {
"href": "/api/v3/groups/26",
"method": "patch"
},
"members": [
{
"href": "/api/v3/users/23",
"title": "Grogu Jarin"
},
{
"href": "/api/v3/users/14",
"title": "Mara Jade"
},
{
"href": "/api/v3/users/3",
"title": "Darth Vader"
}
]
}
}
GroupModel{
"allOf": [
{
"$ref": "#/components/schemas/PrincipalModel"
},
{
"type": "object",
"required": [
"_type",
"_embedded"
],
"properties": {
"_type": {
"type": "string",
"enum": [
"Group"
]
},
"_embedded": {
"type": "object",
"properties": {
"members": {
"type": "array",
"description": "Embedded list of members.",
"items": [
{
"$ref": "#/components/schemas/UserModel"
}
]
}
}
},
"_links": {
"type": "object",
"properties": {
"members": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "A member of the group\n\n# Conditions:\n\n- user has permission `manage_members` in any project\n\n**Resource**: User"
}
]
}
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "An href to delete the group.\n\n# Conditions:\n\n- `admin`"
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "An href to update the group.\n\n# Conditions:\n\n- `admin`\n\n**Resource**: Group"
}
]
}
}
}
}
}
]
}
404
Returned if the group does not exist or if the API user does not have permission to view them.
Required permission If the user has the manage members permission in at least one project the user will be able to query all groups. If not, the user will be able to query all groups which are members in projects, he has the view members permission in.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Update group
Updates the given group by applying the attributes provided in the body.
Please note that the members array provided will override the existing set of members (similar to a PUT). A client thus has to provide the complete list of members the group is to have after the PATCH even if only one member is to be added.
id
integer
required path
Group id
Example:1
200
OK
GroupModel{
"allOf": [
{
"$ref": "#/components/schemas/PrincipalModel"
},
{
"type": "object",
"required": [
"_type",
"_embedded"
],
"properties": {
"_type": {
"type": "string",
"enum": [
"Group"
]
},
"_embedded": {
"type": "object",
"properties": {
"members": {
"type": "array",
"description": "Embedded list of members.",
"items": [
{
"$ref": "#/components/schemas/UserModel"
}
]
}
}
},
"_links": {
"type": "object",
"properties": {
"members": {
"type": "array",
"items": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "A member of the group\n\n# Conditions:\n\n- user has permission `manage_members` in any project\n\n**Resource**: User"
}
]
}
},
"delete": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "An href to delete the group.\n\n# Conditions:\n\n- `admin`"
}
]
},
"updateImmediately": {
"allOf": [
{
"$ref": "#/components/schemas/Link"
},
{
"description": "An href to update the group.\n\n# Conditions:\n\n- `admin`\n\n**Resource**: Group"
}
]
}
}
}
}
}
]
}
400
Occurs when the client did not send a valid JSON object in the request body.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
"message": "The request body was not a single JSON object."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
403
Returned if the client does not have sufficient permissions.
Required permission: Administrator
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the group does not exist or the client does not have sufficient permissions to see it.
Required permission If the user has the manage members permission in at least one project the user will be able to query all groups. If not, the user will be able to query all groups which are members in projects, he has the view members permission in.
Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
422
Returned if:
- a constraint for a property was violated (
PropertyConstraintViolation)
{
"_embedded": {
"details": {
"attribute": "members"
}
},
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
"message": "Member is already taken."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
Delete group
Deletes the group.
id
integer
required path
Group id
Example:1
202
Returned if the group was marked for deletion.
Note that the response body is empty as of now. In future versions of the API a body might be returned, indicating the progress of deletion.
403
Returned if the client does not have sufficient permissions.
Required permission: Administrator
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
"message": "You are not authorized to access this resource."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
404
Returned if the group does not exist or the client does not have sufficient permissions to see it.
Required permission: Administrator
Note: A client without sufficient permissions shall not be able to test for the existence of a version. That’s why a 404 is returned here, even if a 403 might be more appropriate.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
"message": "The requested resource could not be found."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
406
415
Occurs when the client sends an unsupported Content-Type header.
{
"_type": "Error",
"errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
"message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse{
"type": "object",
"required": [
"_type",
"errorIdentifier",
"message"
],
"properties": {
"_embedded": {
"type": "object",
"properties": {
"details": {
"type": "object",
"properties": {
"attribute": {
"type": "string",
"example": "project"
}
}
}
}
},
"_type": {
"type": "string",
"enum": [
"Error"
]
},
"errorIdentifier": {
"type": "string",
"example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
},
"message": {
"type": "string",
"example": "Project can't be blank."
}
}
}
