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/).