Atlassian Workspaces API

openapi: 3.2.0
info:
  title: Atlassian Bitbucket Workspaces API
  description: Code against the Bitbucket API to automate simple tasks, embed Bitbucket data into your own site, build mobile or desktop apps, or even add custom UI add-ons into Bitbucket itself using the Connect framework.
  version: '2.0'
  termsOfService: https://www.atlassian.com/legal/customer-agreement
  contact:
    name: Bitbucket Support
    url: https://support.atlassian.com/bitbucket-cloud/
    email: support@bitbucket.org
servers:
- url: https://api.bitbucket.org/2.0
tags:
- name: Workspaces
  description: 'A workspace is where you create repositories, collaborate on

    your code, and organize different streams of work in your Bitbucket

    Cloud account. Workspaces replace the use of teams and users in API

    calls.

    '
paths:
  /user/permissions/workspaces:
    parameters: []
    get:
      tags:
      - Workspaces
      description: 'Returns an object for each workspace the caller is a member of, and<br>their effective role - the highest level of privilege the caller has.<br>If a user is a member of multiple groups with distinct roles, only the<br>highest level is returned.<br><br>Permissions can be:<br><br>* `owner`<br>* `collaborator`<br>* `member`<br><br>**The `collaborator` role is being removed from the Bitbucket Cloud API. For more information,<br>see the [deprecation announcement](/cloud/bitbucket/deprecation-notice-collaborator-role/).**<br><br>**When you move your administration from Bitbucket Cloud to admin.atlassian.com, the following fields on<br>`workspace_membership` will no longer be present: `last_accessed` and `added_on`. See the<br>[deprecation announcement](/cloud/bitbucket/announcement-breaking-change-workspace-membership/).**<br><br>Results may be further [filtered or sorted](/cloud/bitbucket/rest/intro/#filtering) by<br>workspace or permission by adding the following query string parameters:<br><br>* `q=workspace.slug="bbworkspace1"` or `q=permission="owner"`<br>* `sort=workspace.slug`<br><br>Note that the query parameter values need to be URL escaped so that `=`<br>would become `%3D`.'
      summary: Atlassian List Workspaces For The Current User
      responses:
        '200':
          description: All of the workspace memberships for the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_workspace_memberships'
              examples:
                response:
                  value:
                    pagelen: 10
                    page: 1
                    size: 1
                    values:
                    - type: workspace_membership
                      permission: owner
                      last_accessed: '2019-03-07T12:35:02.900024+00:00'
                      added_on: '2018-10-11T17:42:02.961424+00:00'
                      user:
                        type: user
                        uuid: '{470c176d-3574-44ea-bb41-89e8638bcca4}'
                        nickname: evzijst
                        display_name: Erik van Zijst
                      workspace:
                        type: workspace
                        uuid: '{a15fb181-db1f-48f7-b41f-e1eff06929d6}'
                        slug: bbworkspace1
                        name: Atlassian Bitbucket
        '401':
          description: The request wasn't authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - name: q
        in: query
        description: '

          Query string to narrow down the response. See

          [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering) for details.'
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: '

          Name of a response property to sort results. See

          [filtering and sorting](/cloud/bitbucket/rest/intro/#sorting-query-results)

          for details.

          '
        required: false
        schema:
          type: string
      security:
      - oauth2:
        - account
      - basic: []
      - api_key: []
      operationId: atlassianListWorkspacesForTheCurrentUser
  /workspaces:
    parameters: []
    get:
      tags:
      - Workspaces
      description: Returns a list of workspaces accessible by the authenticated user.<br><br>Results may be further [filtered or sorted](/cloud/bitbucket/rest/intro/#filtering) by<br>workspace or permission by adding the following query string parameters:<br><br>* `q=slug="bbworkspace1"` or `q=is_private=true`<br>* `sort=created_on`<br><br>Note that the query parameter values need to be URL escaped so that `=`<br>would become `%3D`.<br><br>**The `collaborator` role is being removed from the Bitbucket Cloud API. For more information,<br>see the [deprecation announcement](/cloud/bitbucket/deprecation-notice-collaborator-role/).**
      summary: Atlassian List Workspaces For User
      responses:
        '200':
          description: The list of workspaces accessible by the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_workspaces'
              examples:
                response:
                  value:
                    pagelen: 10
                    page: 1
                    size: 1
                    values:
                    - uuid: '{a15fb181-db1f-48f7-b41f-e1eff06929d6}'
                      links:
                        owners:
                          href: https://api.bitbucket.org/2.0/workspaces/bbworkspace1/members?q=permission%3D%22owner%22
                        self:
                          href: https://api.bitbucket.org/2.0/workspaces/bbworkspace1
                        repositories:
                          href: https://api.bitbucket.org/2.0/repositories/bbworkspace1
                        snippets:
                          href: https://api.bitbucket.org/2.0/snippets/bbworkspace1
                        html:
                          href: https://bitbucket.org/bbworkspace1/
                        avatar:
                          href: https://bitbucket.org/workspaces/bbworkspace1/avatar/?ts=1543465801
                        members:
                          href: https://api.bitbucket.org/2.0/workspaces/bbworkspace1/members
                        projects:
                          href: https://api.bitbucket.org/2.0/workspaces/bbworkspace1/projects
                      created_on: '2018-11-14T19:15:05.058566+00:00'
                      type: workspace
                      slug: bbworkspace1
                      is_private: true
                      name: Atlassian Bitbucket
        '401':
          description: The request wasn't authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - name: role
        in: query
        description: "\n            Filters the workspaces based on the authenticated user's role on each workspace.\n\n            * **member**: returns a list of all the workspaces which the caller is a member of\n                at least one workspace group or repository\n            * **collaborator**: returns a list of workspaces which the caller has write access\n                to at least one repository in the workspace\n            * **owner**: returns a list of workspaces which the caller has administrator access\n            "
        required: false
        schema:
          type: string
          enum:
          - owner
          - collaborator
          - member
      - name: q
        in: query
        description: '

          Query string to narrow down the response. See

          [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering) for details.'
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: '

          Name of a response property to sort results. See

          [filtering and sorting](/cloud/bitbucket/rest/intro/#sorting-query-results)

          for details.

          '
        required: false
        schema:
          type: string
      security:
      - oauth2:
        - account
      - basic: []
      - api_key: []
      operationId: atlassianListWorkspacesForUser
  /workspaces/{workspace}:
    parameters:
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Workspaces
      description: Returns the requested workspace.
      summary: Atlassian Get A Workspace
      responses:
        '200':
          description: The workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/workspace'
        '404':
          description: If no workspace exists for the specified name or UUID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2: []
      - basic: []
      - api_key: []
      operationId: atlassianGetAWorkspace
  /workspaces/{workspace}/members:
    parameters:
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Workspaces
      description: Returns all members of the requested workspace.
      summary: Atlassian List Users In A Workspace
      responses:
        '200':
          description: The list of users that are part of a workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_workspace_memberships'
        '401':
          description: The request wasn't authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - account
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:workspace:bitbucket
        - read:user:bitbucket
      operationId: atlassianListUsersInAWorkspace
  /workspaces/{workspace}/members/{member}:
    parameters:
    - name: member
      in: path
      description: Member's UUID or Atlassian ID.
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Workspaces
      description: Returns the workspace membership, which includes<br>a `User` object for the member and a `Workspace` object<br>for the requested workspace.
      summary: Atlassian Get User Membership For A Workspace
      responses:
        '200':
          description: The user that is part of a workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/workspace_membership'
        '401':
          description: The request wasn't authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: A workspace cannot be found, or a user cannot be found, or the user is not a a member of the workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - account
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:workspace:bitbucket
        - read:user:bitbucket
      operationId: atlassianGetUserMembershipForAWorkspace
  /workspaces/{workspace}/permissions:
    parameters:
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Workspaces
      description: 'Returns the list of members in a workspace<br>and their permission levels.<br>Permission can be:<br>* `owner`<br>* `collaborator`<br>* `member`<br><br>**The `collaborator` role is being removed from the Bitbucket Cloud API. For more information,<br>see the [deprecation announcement](/cloud/bitbucket/deprecation-notice-collaborator-role/).**<br><br>**When you move your administration from Bitbucket Cloud to admin.atlassian.com, the following fields on<br>`workspace_membership` will no longer be present: `last_accessed` and `added_on`. See the<br>[deprecation announcement](/cloud/bitbucket/announcement-breaking-change-workspace-membership/).**<br><br>Results may be further [filtered](/cloud/bitbucket/rest/intro/#filtering) by<br>permission by adding the following query string parameters:<br><br>* `q=permission="owner"`'
      summary: Atlassian List User Permissions In A Workspace
      responses:
        '200':
          description: The list of users that are part of a workspace, along with their permission.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_workspace_memberships'
              examples:
                response:
                  value:
                    pagelen: 10
                    values:
                    - permission: owner
                      type: workspace_membership
                      user:
                        type: user
                        uuid: '{470c176d-3574-44ea-bb41-89e8638bcca4}'
                        display_name: Erik van Zijst
                      workspace:
                        type: workspace
                        uuid: '{a15fb181-db1f-48f7-b41f-e1eff06929d6}'
                        slug: bbworkspace1
                        name: Atlassian Bitbucket
                    - permission: member
                      type: workspace_membership
                      user:
                        type: user
                        nickname: seanaty
                        display_name: Sean Conaty
                        uuid: '{504c3b62-8120-4f0c-a7bc-87800b9d6f70}'
                      workspace:
                        type: workspace
                        uuid: '{a15fb181-db1f-48f7-b41f-e1eff06929d6}'
                        slug: bbworkspace1
                        name: Atlassian Bitbucket
                    page: 1
                    size: 2
        '401':
          description: The request wasn't authenticated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - name: q
        in: query
        description: '

          Query string to narrow down the response as per

          [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).'
        required: false
        schema:
          type: string
      security:
      - oauth2:
        - account
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:workspace:bitbucket
        - read:user:bitbucket
      operationId: atlassianListUserPermissionsInAWorkspace
  /workspaces/{workspace}/permissions/repositories:
    parameters:
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Workspaces
      description: 'Returns an object for each repository permission for all of a<br>workspace''s repositories.<br><br>Permissions returned are effective permissions: the highest level of<br>permission the user has. This does not distinguish between direct and<br>indirect (group) privileges.<br><br>Only users with admin permission for the team may access this resource.<br><br>Permissions can be:<br><br>* `admin`<br>* `write`<br>* `read`<br><br>Results may be further [filtered or sorted](/cloud/bitbucket/rest/intro/#filtering)<br>by repository, user, or permission by adding the following query string<br>parameters:<br><br>* `q=repository.name="geordi"` or `q=permission>"read"`<br>* `sort=user.display_name`<br><br>Note that the query parameter values need to be URL escaped so that `=`<br>would become `%3D`.'
      summary: Atlassian List All Repository Permissions For A Workspace
      responses:
        '200':
          description: List of workspace's repository permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_repository_permissions'
              examples:
                response:
                  value:
                    pagelen: 10
                    values:
                    - type: repository_permission
                      user:
                        type: user
                        display_name: Erik van Zijst
                        uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
                      repository:
                        type: repository
                        name: geordi
                        full_name: atlassian_tutorial/geordi
                        uuid: '{85d08b4e-571d-44e9-a507-fa476535aa98}'
                      permission: admin
                    - type: repository_permission
                      user:
                        type: user
                        display_name: Sean Conaty
                        uuid: '{504c3b62-8120-4f0c-a7bc-87800b9d6f70}'
                      repository:
                        type: repository
                        name: geordi
                        full_name: atlassian_tutorial/geordi
                        uuid: '{85d08b4e-571d-44e9-a507-fa476535aa98}'
                      permission: write
                    - type: repository_permission
                      user:
                        type: user
                        display_name: Jeff Zeng
                        uuid: '{47f92a9a-c3a3-4d0b-bc4e-782a969c5c72}'
                      repository:
                        type: repository
                        name: whee
                        full_name: atlassian_tutorial/whee
                        uuid: '{30ba25e9-51ff-4555-8dd0-fc7ee2fa0895}'
                      permission: admin
                    page: 1
                    size: 3
        '403':
          description: The requesting user isn't an admin of the workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - name: q
        in: query
        description: '

          Query string to narrow down the response as per

          [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).'
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: '

          Name of a response property sort the result by as per

          [filtering and sorting](/cloud/bitbucket/rest/intro/#sorting-query-results).

          '
        required: false
        schema:
          type: string
      security:
      - oauth2:
        - account
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
        - read:user:bitbucket
      operationId: atlassianListAllRepositoryPermissionsForAWorkspace
  /workspaces/{workspace}/permissions/repositories/{repo_slug}:
    parameters:
    - name: repo_slug
      in: path
      description: 'This can either be the repository slug or the UUID of the repository,

        surrounded by curly-braces, for example: `{repository UUID}`.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Workspaces
      description: 'Returns an object for the repository permission of each user in the<br>requested repository.<br><br>Permissions returned are effective permissions: the highest level of<br>permission the user has. This does not distinguish between direct and<br>indirect (group) privileges.<br><br>Only users with admin permission for the repository may access this resource.<br><br>Permissions can be:<br><br>* `admin`<br>* `write`<br>* `read`<br><br>Results may be further [filtered or sorted](/cloud/bitbucket/rest/intro/#filtering)<br>by user, or permission by adding the following query string parameters:<br><br>* `q=permission>"read"`<br>* `sort=user.display_name`<br><br>Note that the query parameter values need to be URL escaped so that `=`<br>would become `%3D`.'
      summary: Atlassian List A Repository Permissions For A Workspace
      responses:
        '200':
          description: The repository permission for all users in this repository.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_repository_permissions'
              examples:
                response:
                  value:
                    pagelen: 10
                    values:
                    - type: repository_permission
                      user:
                        type: user
                        display_name: Erik van Zijst
                        uuid: '{d301aafa-d676-4ee0-88be-962be7417567}'
                      repository:
                        type: repository
                        name: geordi
                        full_name: atlassian_tutorial/geordi
                        uuid: '{85d08b4e-571d-44e9-a507-fa476535aa98}'
                      permission: admin
                    - type: repository_permission
                      user:
                        type: user
                        display_name: Sean Conaty
                        uuid: '{504c3b62-8120-4f0c-a7bc-87800b9d6f70}'
                      repository:
                        type: repository
                        name: geordi
                        full_name: atlassian_tutorial/geordi
                        uuid: '{85d08b4e-571d-44e9-a507-fa476535aa98}'
                      permission: write
                    page: 1
                    size: 2
        '403':
          description: The requesting user isn't an admin of the repository.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      parameters:
      - name: q
        in: query
        description: '

          Query string to narrow down the response as per

          [filtering and sorting](/cloud/bitbucket/rest/intro/#filtering).'
        required: false
        schema:
          type: string
      - name: sort
        in: query
        description: '

          Name of a response property sort the result by as per

          [filtering and sorting](/cloud/bitbucket/rest/intro/#sorting-query-results).

          '
        required: false
        schema:
          type: string
      security:
      - oauth2:
        - repository
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
        - read:user:bitbucket
      operationId: atlassianListARepositoryPermissionsForAWorkspace
  /workspaces/{workspace}/projects:
    parameters:
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Workspaces
      description: Returns the list of projects in this workspace.
      summary: Atlassian List Projects In A Workspace
      responses:
        '200':
          description: The list of projects in this workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_projects'
        '404':
          description: A workspace doesn't exist at this location.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - project
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:project:bitbucket
      operationId: atlassianListProjectsInAWorkspace
components:
  schemas:
    workspace_membership:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Workspace Membership
        description: "A Bitbucket workspace membership.\n            Links a user to a workspace."
        properties:
          links:
            type: object
            properties:
              self:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
            additionalProperties: false
          user:
            $ref: '#/components/schemas/account'
          workspace:
            $ref: '#/components/schemas/workspace'
        additionalProperties: true
    repository:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Repository
        description: A Bitbucket repository.
        properties:
          links:
            type: object
            properties:
              self:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
              html:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
              avatar:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
              pullrequests:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
              commits:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
              forks:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
              watchers:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
              downloads:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
              clone:
                type: array
                items:
                  type: object
                  title: Link
                  description: A link to a resource related to this object.
                  properties:
                    href:
                      type: string
                      format: uri
                    name:
                      type: string
                  additionalProperties: false
              hooks:
                type: object
                title: Link
                description: A link to a resource related to this object.
                properties:
                  href:
                    type: string
                    format: uri
                  name:
                    type: string
                additionalProperties: false
            additionalProperties: false
          uuid:
            type: string
            description: The repository's immutable id. This can be used as a substitute for the slug segment in URLs. Doing this guarantees your URLs will survive renaming of the repository by its owner, or even transfer of the repository to a different user.
          full_name:
            type: string
            description: The concatenation of the repository owner's username and the slugified name, e.g. "evzijst/interruptingcow". This is the same string used in Bitbucket URLs.
          is_private:
            type: boolean
          parent:
            $ref: '#/components/schemas/repository'
          scm:
            type: string
            enum:
            - git
          owner:
            $ref: '#/components/schemas/account'
          name:
            type: string
          description:
            type: string
          created_on:
            type: string
            format: date-time
          updated_on:
            type: string
            format: date-time
          size:
            type: integer
          language:
            type: string
          has_issues:
            type: boolean
            description: '

              The issue tracker for this repository is enabled. Issue Tracker

              features are not supported for repositories in workspaces

              administered through admin.atlassian.com.

              '
          has_wiki:
            type: boolean
            description: '

              The wiki for this repository is enabled. Wiki

              features are not supported for repositories in workspaces

              administered through admin.atlassian.com.

              '
          fork_policy:
            type: string
            description: "\nControls the rules for forking this repository.\n\n* **allow_forks**: unrestricted forking\n* **no_public_forks**: restrict forking to private forks (forks cannot\n  be made public later)\n* **no_forks**: deny all forking\n"
            enum:
            - allow_forks
            - no_public_forks
            - no_forks
          project:
            $ref: '#/components/schemas/project'
          mainbranch:
            $ref: '#/components/schemas/branch'


# --- truncated at 32 KB (163 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/atlassian/refs/heads/main/openapi/atlassian-workspaces-api-openapi.yml