Atlassian Restriction API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Restriction API
  description: The Atlassian Admin API provides programmatic access to manage Atlassian organizations, users, domains, policies, and events. It enables administrators to automate organization management tasks, integrate with identity providers, and ensure appropriate access to Atlassian products.
  version: 1.0.0
  contact:
    name: Atlassian Developer
    url: https://developer.atlassian.com/cloud/admin/
  license:
    name: Atlassian Developer Terms
    url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  x-logo:
    url: https://wac-cdn.atlassian.com/assets/img/favicons/atlassian/favicon.png
servers:
- url: https://api.atlassian.com
  description: Atlassian Cloud API
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Restriction
paths:
  /repositories/{workspace}/{repo_slug}/branch-restrictions:
    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
    post:
      tags:
      - Restriction
      description: This API operation creates a new branch restriction rule for a specific repository in Bitbucket Cloud, allowing workspace administrators to enforce policies on branches within a given repository. By sending a POST request to the endpoint with the workspace ID and repository slug as path parameters, users can define restrictions such as preventing force pushes, requiring pull request approvals, limiting who can merge or push to specific branches, or enforcing other branch protection policies. The request body typically includes details like the restriction type, the branch pattern to which the rule applies (using glob patterns or specific branch names), and the users or groups affected by the restriction. This functionality is essential for maintaining code quality and implementing workflow controls in collaborative development environments, ensuring that critical branches like main or production are protected from unauthorized or potentially harmful changes.
      summary: Atlassian Create Branch Restriction Rule
      responses:
        '201':
          description: A paginated list of branch restrictions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branchrestriction'
              examples:
                branch-restriction_2:
                  $ref: '#/components/examples/branch-restriction_2'
        '401':
          description: If the request was not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have admin access to the repository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the repository does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/branchrestriction'
            examples:
              branch-restriction:
                $ref: '#/components/examples/branch-restriction'
        description: The new rule
        required: true
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:repository:bitbucket
      operationId: createBranchRestrictionRule
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationRequestSchema: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /repositories/{workspace}/{repo_slug}/branch-restrictions/{id}:
    parameters:
    - name: id
      in: path
      description: The restriction rule's id
      required: true
      schema:
        type: string
    - 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
    delete:
      tags:
      - Restriction
      description: The Delete Branch Restriction Rule operation in the Atlassian Bitbucket Repositories API allows you to remove a specific branch restriction rule from a repository by making a DELETE request to the endpoint /repositories/{workspace}/{repo_slug}/branch-restrictions/{id}. This operation requires you to specify the workspace name, repository slug, and the unique identifier of the branch restriction rule you want to delete. Branch restrictions are used to enforce policies on branches, such as preventing direct pushes, requiring pull requests, or limiting who can merge changes. By deleting a branch restriction rule, you effectively remove those constraints from the specified branches in your repository. This operation is useful when you need to modify your repository's branch protection strategy, remove outdated restrictions, or adjust team workflows. Authentication and appropriate permissions are required to execute this operation successfully, as it affects repository security and collaboration policies.
      summary: Atlassian Delete Branch Restriction Rule
      responses:
        '204':
          description: ''
        '401':
          description: If the request was not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have admin access to the repository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the repository or branch restriction id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:repository:bitbucket
      operationId: deleteBranchRestrictionRule
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    get:
      tags:
      - Restriction
      description: The GET operation on the /repositories/{workspace}/{repo_slug}/branch-restrictions/{id} endpoint in the Atlassian Bitbucket Repositories API retrieves detailed information about a specific branch restriction rule within a repository. By providing the workspace identifier, repository slug, and the unique ID of the branch restriction, this operation returns the complete configuration of that particular rule, including its type (such as requiring pull request approvals, restricting pushes, or enforcing merge checks), the branch pattern it applies to, the users or groups it affects, and any associated permissions or conditions. This endpoint is useful for administrators and developers who need to audit existing branch protection settings, verify security policies, or programmatically inspect repository governance rules before making modifications.
      summary: Atlassian Get Branch Restriction Rule
      responses:
        '200':
          description: The branch restriction rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branchrestriction'
              examples:
                branch-restriction_2:
                  $ref: '#/components/examples/branch-restriction_2'
        '401':
          description: If the request was not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have admin access to the repository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the repository or branch restriction id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:repository:bitbucket
      operationId: getBranchRestrictionRule
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Restriction
      description: This API operation allows you to modify an existing branch restriction rule in a Bitbucket repository by specifying the workspace, repository slug, and the unique identifier of the restriction rule you want to update. The PUT request enables you to change the configuration of access controls and permissions that govern who can push, merge, or perform other operations on specific branches within the repository. You can adjust parameters such as the branch pattern the rule applies to, the type of restriction (like requiring pull requests or limiting direct pushes), and which users or groups are affected by or exempt from the rule. This is particularly useful for maintaining code quality and enforcing workflow policies as your team's requirements evolve, allowing administrators to refine branch protection rules without having to delete and recreate them from scratch.
      summary: Atlassian Update Branch Restriction Rule
      responses:
        '200':
          description: The updated branch restriction rule
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branchrestriction'
              examples:
                branch-restriction_2:
                  $ref: '#/components/examples/branch-restriction_2'
        '401':
          description: If the request was not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have admin access to the repository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the repository or branch restriction id does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/branchrestriction'
            examples:
              branch-restriction:
                $ref: '#/components/examples/branch-restriction'
        description: The new version of the existing rule
        required: true
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:repository:bitbucket
      operationId: updateBranchRestrictionRule
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationRequestSchema: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    account:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Account
        description: An account object.
        properties:
          links:
            $ref: '#/components/schemas/account_links'
          created_on:
            type: string
            format: date-time
          display_name:
            type: string
          username:
            type: string
            pattern: ^[a-zA-Z0-9_\-]+$
          uuid:
            type: string
        additionalProperties: true
    workspace:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Workspace
        description: "A Bitbucket workspace.\n            Workspaces are used to organize repositories."
        properties:
          links:
            type: object
            properties:
              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
              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
              members:
                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
              owners:
                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
              projects:
                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
              repositories:
                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
              snippets:
                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
              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
          uuid:
            type: string
            description: The workspace's immutable id.
          name:
            type: string
            description: The name of the workspace.
          slug:
            type: string
            description: The short label that identifies this workspace.
          is_private:
            type: boolean
            description: 'Indicates whether the workspace is publicly accessible, or whether it is

              private to the members and consequently only visible to members.'
          created_on:
            type: string
            format: date-time
          updated_on:
            type: string
            format: date-time
        additionalProperties: true
    error:
      type: object
      title: Error
      description: Base type for most resource objects. It defines the common `type` element that identifies an object's type. It also identifies the element as Swagger's `discriminator`.
      properties:
        type:
          type: string
          example: example_value
        error:
          type: object
          properties:
            message:
              type: string
            detail:
              type: string
            data:
              type: object
              description: Optional structured data that is endpoint-specific.
              properties: {}
              additionalProperties: true
          required:
          - message
          additionalProperties: false
          example: example_value
      required:
      - type
      additionalProperties: true
    branchrestriction:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Branch Restriction
        description: A branch restriction rule.
        properties:
          users:
            type: array
            items:
              $ref: '#/components/schemas/account'
            minItems: 0
          groups:
            type: array
            items:
              $ref: '#/components/schemas/group'
            minItems: 0
        additionalProperties: true
    object:
      type: object
      description: Base type for most resource objects. It defines the common `type` element that identifies an object's type. It also identifies the element as Swagger's `discriminator`.
      properties:
        type:
          type: string
          example: example_value
      required:
      - type
      additionalProperties: true
      discriminator:
        propertyName: type
    group:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Group
        description: A group object
        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
            additionalProperties: false
          owner:
            $ref: '#/components/schemas/account'
          workspace:
            $ref: '#/components/schemas/workspace'
          name:
            type: string
          slug:
            type: string
            description: 'The "sluggified" version of the group''s name. This contains only ASCII

              characters and can therefore be slightly different than the name'
          full_slug:
            type: string
            description: 'The concatenation of the workspace''s slug and the group''s slug,

              separated with a colon (e.g. `acme:developers`)

              '
        additionalProperties: true
    link:
      type: object
      title: Link
      description: A link to a resource related to this object.
      properties:
        href:
          type: string
          format: uri
          example: https://www.example.com
        name:
          type: string
          example: Example Title
      additionalProperties: false
    account_links:
      type: object
      title: Account Links
      description: Links related to an Account.
      properties:
        avatar:
          $ref: '#/components/schemas/link'
      additionalProperties: true
  examples:
    branch-restriction_2:
      users:
        links:
          self:
            href: https://api.bitbucket.org/2.0/users/example_user
        created_on: '2023-01-15T10:30:00Z'
        display_name: John Doe
        username: john_doe
        uuid: '{12345678-1234-1234-1234-123456789abc}'
      groups:
        links:
          self:
            href: https://api.bitbucket.org/2.0/groups/example_workspace/developers
            name: developers
          html:
            href: https://bitbucket.org/example_workspace/developers
            name: developers
        owner:
          created_on: '2022-05-20T08:15:00Z'
          display_name: Jane Smith
          username: jane_smith
          uuid: '{87654321-4321-4321-4321-cba987654321}'
        workspace:
          slug: example_workspace
          name: Example Workspace
          uuid: '{abcdef12-abcd-abcd-abcd-abcdef123456}'
        name: Developers
        slug: developers
        full_slug: example_workspace:developers
    branch-restriction:
      users:
        links:
          self:
            href: https://api.bitbucket.org/2.0/users/johndoe
        created_on: '2023-01-15T10:30:00Z'
        display_name: John Doe
        username: johndoe
        uuid: '{12345678-1234-1234-1234-123456789abc}'
      groups:
        links:
          self:
            href: https://api.bitbucket.org/2.0/workspaces/acme/groups/developers
            name: developers
          html:
            href: https://bitbucket.org/acme/workspace/settings/groups/developers
            name: developers
        owner:
          created_on: '2022-05-10T08:00:00Z'
          display_name: Acme Corp
          username: acme
          uuid: '{87654321-4321-4321-4321-cba987654321}'
        workspace:
          slug: acme
          name: Acme Corporation
        name: Developers
        slug: developers
        full_slug: acme:developers
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Use an Atlassian API key as a Bearer token. Create API keys at https://admin.atlassian.com.
    oauth2:
      type: oauth2
      description: OAuth 2.0 authorization for Atlassian Cloud APIs.
      flows:
        authorizationCode:
          authorizationUrl: https://auth.atlassian.com/authorize
          tokenUrl: https://auth.atlassian.com/oauth/token
          scopes:
            read:org:admin: Read organization information.
            write:org:admin: Modify organization settings.
            read:user:admin: Read user information.
            write:user:admin: Modify user accounts.
            read:policy:admin: Read organization policies.
            write:policy:admin: Modify organization policies.
            read:event:admin: Read organization events.
externalDocs:
  description: Atlassian Admin REST API Documentation
  url: https://developer.atlassian.com/cloud/admin/organization/rest/intro/