Atlassian Confluence Group API
The Atlassian Confluence Group API enables management of user groups within Confluence including membership and access control.
OpenAPI Specification
openapi: 3.0.1
info:
title: 'Atlassian wiki/rest/api/group/'
description: Needs description.
termsOfService: https://atlassian.com/terms/
version: 1.0.0
externalDocs:
description: The online and complete version of the Confluence Cloud REST API docs.
url: https://developer.atlassian.com/cloud/confluence/rest/
servers:
- url: //your-domain.atlassian.net
tags:
- name: Group
paths:
/wiki/rest/api/group/by-name:
get:
tags:
- Group
summary: Atlassian Get Group
description: >-
Returns a user group for a given group
name.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to access the Confluence site ('Can use'
global permission).
operationId: atlassianGetgroupbyqueryparam
parameters:
- name: name
in: query
description: |-
The name of the group. This is the same as the group name shown in
the Confluence administration console.
required: true
schema:
type: string
responses:
'200':
description: Returned if the requested group is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'403':
description: |-
Returned if the calling user does not have permission to view
groups.
content: {}
'404':
description: Returned if the group does not exist.
content: {}
deprecated: true
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-groups
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-groups
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:group:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: READ
/wiki/rest/api/group/by-id:
get:
tags:
- Group
summary: Atlassian Get Group
description: >-
Returns a user group for a given group
id.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to access the Confluence site ('Can use'
global permission).
operationId: atlassianGetgroupbygroupid
parameters:
- name: id
in: query
description: The id of the group.
required: true
schema:
type: string
responses:
'200':
description: Returned if the requested group is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'403':
description: |-
Returned if the calling user does not have permission to view
groups.
content: {}
'404':
description: Returned if the group does not exist.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-groups
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-groups
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:group:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: READ
delete:
tags:
- Group
summary: Atlassian Delete User Group
description: >-
Delete user
group.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>User must be a site admin.
operationId: atlassianRemovegroupbyid
parameters:
- name: id
in: query
description: Id of the group to delete.
required: true
schema:
type: string
responses:
'204':
description: Returned if the group was removed successfully.
content: {}
'400':
description: Returned if the id is missing or invalid.
content: {}
'401':
description: Returned if the calling user is not logged in to Confluence.
content: {}
'403':
description: Returned if the user is not a site admin.
content: {}
'404':
description: If no user group by the given id exists.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-groups
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-groups
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:group:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: INACCESSIBLE
/wiki/rest/api/group/{groupName}:
get:
tags:
- Group
summary: Atlassian Get Group
description: >-
Returns a user group for a given group name.<br><br>Use updated Get
group
API<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to access the Confluence site ('Can use'
global permission).
operationId: atlassianGetgroupbyname
parameters:
- name: groupName
in: path
description: |-
The name of the group. This is the same as the group name shown in
the Confluence administration console.
required: true
schema:
type: string
responses:
'200':
description: Returned if the requested group is returned.
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'403':
description: |-
Returned if the calling user does not have permission to view
groups.
content: {}
'404':
description: Returned if the group does not exist.
content: {}
deprecated: true
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: READ
/wiki/rest/api/group/member:
get:
tags:
- Group
summary: Atlassian Get Group Members
description: >-
Returns the users that are members of a
group.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to access the Confluence site ('Can use'
global permission).
operationId: atlassianGetmembersbyqueryparam
parameters:
- name: name
in: query
description: The name of the group to be queried for its members.
required: true
schema:
type: string
- name: start
in: query
description: The starting index of the returned users.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: >-
The maximum number of users to return per page.
Note, this is restricted by fixed system limit of 200 which is to
say if the limit parameter
exceeds 200, this API will return a maximum of 200 users per page.
schema:
minimum: 0
type: integer
format: int32
default: 200
- name: shouldReturnTotalSize
in: query
description: >-
Whether to include total size parameter in the results.
Note, fetching total size property is an expensive operation; use it
if your use case needs this value.
schema:
type: boolean
default: false
- name: expand
in: query
description: |-
A multi-value parameter indicating which properties of the user to
expand.
- `operations` returns the operations that the user is allowed to do.
- `personalSpace` returns the user's personal space, if it exists.
- `isExternalCollaborator` returns whether the user is an external collaborator user.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- operations
- personalSpace
- isExternalCollaborator
responses:
'200':
description: Returned if the requested users are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/UserArray'
'403':
description: Returned if the calling user does not have permission to view users.
content: {}
deprecated: true
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-groups
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-groups
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:group:confluence
- read:user:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: READ
/wiki/rest/api/group/{groupName}/member:
get:
tags:
- Group
summary: Atlassian Get Group Members
description: >-
Returns the users that are members of a group.<br><br>Use updated Get
group
API<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to access the Confluence site ('Can use'
global permission).
operationId: atlassianGetgroupmembers
parameters:
- name: groupName
in: path
description: The name of the group to be queried for its members.
required: true
schema:
type: string
- name: start
in: query
description: The starting index of the returned users.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of users to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 200
responses:
'200':
description: Returned if the requested users are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/UserArray'
'400':
description: Returned if given limit is greater than 200
content: {}
'403':
description: Returned if the calling user does not have permission to view users.
content: {}
deprecated: true
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: READ
/wiki/rest/api/group/picker:
get:
tags:
- Group
summary: Atlassian Search Groups By Partial Query
description: Get search results of groups by partial query provided.
operationId: atlassianSearchgroups
parameters:
- name: query
in: query
description: the search term used to query results.
required: true
schema:
type: string
- name: start
in: query
description: The starting index of the returned groups.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of groups to return per page.
Note, this is restricted to a maximum limit of 200 groups.
schema:
minimum: 0
type: integer
format: int32
default: 200
- name: shouldReturnTotalSize
in: query
description: >-
Whether to include total size parameter in the results.
Note, fetching total size property is an expensive operation; use it
if your use case needs this value.
schema:
type: boolean
default: false
responses:
'200':
description: Returns a full JSON representation of group collection.
content:
application/json:
schema:
$ref: '#/components/schemas/GroupArrayWithLinks'
'403':
description: |-
Returned if the calling user does not have permission to view
groups.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-groups
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-groups
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:group:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: READ
/wiki/rest/api/group/userByGroupId:
post:
tags:
- Group
summary: Atlassian Add Member To Group By Groupid
description: >-
Adds a user as a member in a group represented by its
groupId<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>User must be a site admin.
operationId: atlassianAddusertogroupbygroupid
parameters:
- name: groupId
in: query
description: GroupId of the group whose membership is updated
required: true
schema:
type: string
requestBody:
description: AccountId of the user who needs to be added as member.
content:
application/json:
schema:
$ref: '#/components/schemas/AccountId'
required: true
responses:
'201':
description: Returned if the group was created successfully.
content: {}
'400':
description: Returned if the groupId or accountId are missing or invalid.
content: {}
'401':
description: Returned if the calling user is not logged in to Confluence.
content: {}
'403':
description: Returned if the user is not a site admin.
content: {}
'404':
description: If no user group by the give name exists.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-groups
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-groups
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:group:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-codegen-request-body-name: body
x-atlassian-connect-scope: INACCESSIBLE
delete:
tags:
- Group
summary: Atlassian Remove Member From Group Using Group Id
description: >-
Remove user as a member from a
group.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>User must be a site admin.
operationId: atlassianRemovememberfromgroupbygroupid
parameters:
- name: groupId
in: query
description: Id of the group whose membership is updated.
required: true
schema:
type: string
- $ref: '#/components/parameters/userLookupKey'
- $ref: '#/components/parameters/userLookupUsername'
- $ref: '#/components/parameters/userLookupAccountId'
responses:
'204':
description: Returned if the group was removed successfully.
content: {}
'400':
description: Returned if the name is missing or invalid.
content: {}
'401':
description: Returned if the calling user is not logged in to Confluence.
content: {}
'403':
description: |-
Returned if the user is not a site admin.
Note: A 204 is returned if the user is not part of the
group.
content: {}
'404':
description: |-
If no user group by the give name exists or if no user exists
for the given accountId.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-groups
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-groups
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:group:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: INACCESSIBLE
/wiki/rest/api/group/{groupId}/membersByGroupId:
get:
tags:
- Group
summary: Atlassian Get Group Members
description: >-
Returns the users that are members of a group.<br><br>Use updated Get
group
API<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>Permission to access the Confluence site ('Can use'
global permission).
operationId: atlassianGetgroupmembersbygroupid
parameters:
- name: groupId
in: path
description: The id of the group to be queried for its members.
required: true
schema:
type: string
- name: start
in: query
description: The starting index of the returned users.
schema:
minimum: 0
type: integer
format: int32
default: 0
- name: limit
in: query
description: |-
The maximum number of users to return per page.
Note, this may be restricted by fixed system limits.
schema:
minimum: 0
type: integer
format: int32
default: 200
- name: shouldReturnTotalSize
in: query
description: >-
Whether to include total size parameter in the results.
Note, fetching total size property is an expensive operation; use it
if your use case needs this value.
schema:
type: boolean
default: false
- name: expand
in: query
description: |-
A multi-value parameter indicating which properties of the user to
expand.
- `operations` returns the operations that the user is allowed to do.
- `personalSpace` returns the user's personal space, if it exists.
- `isExternalCollaborator` returns whether the user is an external collaborator user.
style: form
explode: false
schema:
type: array
items:
type: string
enum:
- operations
- personalSpace
- isExternalCollaborator
responses:
'200':
description: Returned if the requested users are returned.
content:
application/json:
schema:
$ref: '#/components/schemas/UserArray'
'400':
description: Returned if given limit is greater than 200
content: {}
'403':
description: Returned if the calling user does not have permission to view users.
content: {}
security:
- basicAuth: []
- oAuthDefinitions:
- read:confluence-groups
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- read:confluence-groups
- scheme: oAuthDefinitions
state: Beta
scopes:
- read:group:confluence
- read:user:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: READ
/wiki/rest/api/group/user:
post:
tags:
- Group
summary: Atlassian Add Member To Group
description: >-
Adds a user as a member in a
group.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>User must be a site admin.
operationId: atlassianAddusertogroup
parameters:
- name: name
in: query
description: Name of the group whose membership is updated
required: true
schema:
type: string
requestBody:
description: AccountId of the user who needs to be added as member.
content:
application/json:
schema:
$ref: '#/components/schemas/AccountId'
required: true
responses:
'201':
description: Returned if the group was created successfully.
content: {}
'400':
description: Returned if the name or accountId are missing or invalid.
content: {}
'401':
description: Returned if the calling user is not logged in to Confluence.
content: {}
'403':
description: Returned if the user is not a site admin.
content: {}
'404':
description: If no user group by the give name exists.
content: {}
deprecated: true
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-groups
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-groups
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:group:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-codegen-request-body-name: body
x-atlassian-connect-scope: INACCESSIBLE
delete:
tags:
- Group
summary: Atlassian Remove Member From Group
description: >-
Remove user as a member from a
group.<br><br>**[Permissions](https://confluence.atlassian.com/x/_AozKw)
required**:<br>User must be a site admin.
operationId: atlassianRemovememberfromgroup
parameters:
- name: name
in: query
description: Name of the group whose membership is updated.
required: true
schema:
type: string
- $ref: '#/components/parameters/userLookupKey'
- $ref: '#/components/parameters/userLookupUsername'
- $ref: '#/components/parameters/userLookupAccountId'
responses:
'204':
description: Returned if the group was removed successfully.
content: {}
'400':
description: Returned if the name is missing or invalid.
content: {}
'401':
description: Returned if the calling user is not logged in to Confluence.
content: {}
'403':
description: |-
Returned if the user is not a site admin.
Note: A 204 is returned if the user is not part of the
group.
content: {}
'404':
description: |-
If no user group by the give name exists or if no user exists
for the given accountId.
content: {}
deprecated: true
security:
- basicAuth: []
- oAuthDefinitions:
- write:confluence-groups
x-atlassian-oauth2-scopes:
- scheme: oAuthDefinitions
state: Current
scopes:
- write:confluence-groups
- scheme: oAuthDefinitions
state: Beta
scopes:
- write:group:confluence
x-atlassian-data-security-policy:
- app-access-rule-exempt: true
x-atlassian-connect-scope: INACCESSIBLE
components:
schemas:
Group:
required:
- name
- type
- id
type: object
properties:
type:
type: string
default: group
enum:
- group
name:
type: string
id:
type: string
_links:
$ref: '#/components/schemas/GenericLinks'
UserArray:
required:
- results
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/User'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
totalSize:
type: integer
format: int64
default: 0
description: >-
This property will return total count of the objects before
pagination is applied.
This value is returned if `shouldReturnTotalSize` is set to `true`.
_links:
$ref: '#/components/schemas/GenericLinks'
GroupArrayWithLinks:
description: Same as GroupArray but with `_links` property.
required:
- limit
- results
- size
- start
- _links
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Group'
start:
type: integer
format: int32
limit:
type: integer
format: int32
size:
type: integer
format: int32
totalSize:
type: integer
format: int64
default: 0
description: >-
This property will return total count of the objects before
pagination is applied.
This value is returned if `shouldReturnTotalSize` is set to `true`.
_links:
$ref: '#/components/schemas/GenericLinks'
x-atlassian-narrative:
documents:
- title: About
anchor: about
body: >-
This is the reference for the Confluence Cloud REST API. This API is the
primary way to get and
modify data in Confluence Cloud, whether you are developing an app or
any other integration.
Use it to interact with Confluence entities, like pages and blog posts,
spaces, users, groups,
and more.
- title: Authentication and authorization
anchor: auth
body: >-
**Authentication:** If you are building a Cloud app, authentication is
implemented via JWT or OAuth 2.0, depending on what you are building
(see [Security
overview](https://developer.atlassian.com/cloud/confluence/security-overview/)).
Otherwise, if you are authenticating directly against the REST API, the
REST API supports basic auth (see [Basic auth for REST
APIs](https://developer.atlassian.com/cloud/confluence/basic-auth-for-rest-apis/)).
**Authorization:** If you are building a Cloud app, authorization can be
implemented by
[scopes](https://developer.atlassian.com/cloud/confluence/scopes/) or by
[OAuth 2.0 user
impersonation](https://developer.atlassian.com/cloud/confluence/oauth-2-jwt-bearer-tokens-for-apps).
Otherwise, if you are making calls directly against the REST API,
authorization is based on the user used in the authentication process.
See [Security
overview](https://developer.atlassian.com/cloud/confluence/security-overview/)
for more details on authentication and authorization.
- title: Status codes
anchor: status-code
body: >-
The Confluence REST API uses the [standard HTTP status
codes](https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html).
Responses that return an error status code will also return a response
body, similar to the following:
```json
{
"statusCode": 404,
"data": {
"authorized": false,
"valid": false,
"errors": [
{
"message": {
"translation": "This is an example error message.",
"args": []
}
}
],
"successful": false
},
"message": "This is an example error message."
}
```
- title: Using the REST API
anchor: using
body: >-
**Expansion:** The Confluence REST API uses resource expansion: some
parts of a resource are not returned unless explicitly specified. This
simplifies responses and minimizes network traffic.
To expand part of a resource in a request, use the `expand` query
parameter and specify the entities to be expanded. If you need to expand
nested entities, use the `.` dot notation. For example, the following
request will expand information about the requested content's space and
labels:
```
GET /wiki/rest/api/content/{id}?expand=space,metadata.labels
```
**Pagination:** The Confluence REST API uses pagination: a method that
returns a response with multiple objects can only return a limited
number at one time. This limits the size of responses and conserves
server resources.
Use the 'limit' and 'start' query parameters to specify pagination:
- `limit` is the number of objects to return per page. This may be
restricted by system limits.
- `start` is the index of the first item returned in the page of
results. The base index is 0.
For example, the following request will return ten content objects,
starting from the fifth object.
```
GET /wiki/rest/api/content?start=4&limit=10
```
**Special headers:**
- `X-Atlassian-Token: no-check` request header must be specified for
methods
that are protected from Cross Site Request Forgery (XSRF/CSRF) attacks.
This is
stated in the method description, if required. For more information, see
this
[KB
article](https://confluence.atlassian.com/cloudkb/xsrf-check-failed-when-calling-cloud-apis-826874382.html).
- title: Capabilities
anchor: capabilities
body: >-
**Webhooks:** A webhook is a user-defined callback over HTTP. You can
use Confluence webhooks to notify your app or web application when
certain events occur in Confluence. For example, when a page is created
or updated. To learn more, see
[Webhooks](https://developer.atlassian.com/cloud/confluence/modules/webhook/).
**Content properties:** Content properties are a key-value storage
associated with a piece of Confluence content. If you are building an
app, this is one form of persistence that you can use. You can use the
Confluence REST API to get, update, and delete content properties. To
learn more, see [Content properties in the REST
API](https://developer.atlassian.com/cloud/confluence/content-properties/).
**CQL:** The Confluence Query Language (CQL) allows you to perform
complex searches for content using an SQL-like syntax in the `search`
resource. To learn more, see [Advanced searching using
CQL](https://developer.atlassian.com/cloud/confluence/advanced-searching-using-cql/).