Bitbucket Branching model API

swagger: '2.0'
info:
  title: Bitbucket Addon Branching model 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
host: api.bitbucket.org
basePath: /2.0
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Branching model
  description: 'The branching model resource is used to modify the branching model

    for a repository.


    You can use the branching model to define a branch based workflow

    for your repositories. When you map your workflow to branch types,

    you can ensure that branches are named consistently by configuring

    which branch types to make available.

    '
paths:
  /repositories/{workspace}/{repo_slug}/branching-model:
    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
      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
      type: string
    get:
      tags:
      - Branching model
      description: "Return the branching model as applied to the repository. This view is\nread-only. The branching model settings can be changed using the\n[settings](#api-repositories-workspace-repo-slug-branching-model-settings-get) API.\n\nThe returned object:\n\n1. Always has a `development` property. `development.branch` contains\n   the actual repository branch object that is considered to be the\n   `development` branch. `development.branch` will not be present\n   if it does not exist.\n2. Might have a `production` property. `production` will not\n   be present when `production` is disabled.\n   `production.branch` contains the actual branch object that is\n   considered to be the `production` branch. `production.branch` will\n   not be present if it does not exist.\n3. Always has a `branch_types` array which contains all enabled branch\n   types."
      summary: Get the branching model for a repository
      responses:
        '200':
          description: The branching model object
          schema:
            $ref: '#/definitions/branching_model'
          examples:
            application/json:
              development:
                name: master
                branch:
                  type: branch
                  name: master
                  target:
                    hash: 16dffcb0de1b22e249db6799532074cf32efe80f
                use_mainbranch: true
              production:
                name: production
                branch:
                  type: branch
                  name: production
                  target:
                    hash: 16dffcb0de1b22e249db6799532074cf32efe80f
                use_mainbranch: false
              branch_types:
              - kind: release
                prefix: release/
              - kind: hotfix
                prefix: hotfix/
              - kind: feature
                prefix: feature/
              - kind: bugfix
                prefix: bugfix/
              type: branching_model
              links:
                self:
                  href: https://api.bitbucket.org/.../branching-model
        '401':
          description: If the request was not authenticated
          schema:
            $ref: '#/definitions/error'
        '403':
          description: If the authenticated user does not have read access to the repository
          schema:
            $ref: '#/definitions/error'
        '404':
          description: If the repository does not exist
          schema:
            $ref: '#/definitions/error'
      parameters: []
      security:
      - oauth2:
        - repository
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
  /repositories/{workspace}/{repo_slug}/branching-model/settings:
    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
      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
      type: string
    get:
      tags:
      - Branching model
      description: "Return the branching model configuration for a repository. The returned\nobject:\n\n1. Always has a `development` property for the development branch.\n2. Always a `production` property for the production branch. The\n   production branch can be disabled.\n3. The `branch_types` contains all the branch types.\n4. `default_branch_deletion` indicates whether branches will be\n    deleted by default on merge.\n\nThis is the raw configuration for the branching model. A client\nwishing to see the branching model with its actual current branches may\nfind the [active model API](/cloud/bitbucket/rest/api-group-branching-model/#api-repositories-workspace-repo-slug-branching-model-get) more useful."
      summary: Get the branching model config for a repository
      responses:
        '200':
          description: The branching model configuration
          schema:
            $ref: '#/definitions/branching_model_settings'
          examples:
            application/json:
              development:
                is_valid: true
                name: 'null'
                use_mainbranch: true
              production:
                is_valid: true
                name: production
                use_mainbranch: false
                enabled: false
              branch_types:
              - kind: release
                enabled: true
                prefix: release/
              - kind: hotfix
                enabled: true
                prefix: hotfix/
              - kind: feature
                enabled: true
                prefix: feature/
              - kind: bugfix
                enabled: false
                prefix: bugfix/
              type: branching_model_settings
              links:
                self:
                  href: https://api.bitbucket.org/.../branching-model/settings
              default_branch_deletion: 'false'
        '401':
          description: If the request was not authenticated
          schema:
            $ref: '#/definitions/error'
        '403':
          description: If the authenticated user does not have admin access to the repository
          schema:
            $ref: '#/definitions/error'
        '404':
          description: If the repository does not exist
          schema:
            $ref: '#/definitions/error'
      parameters: []
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:repository:bitbucket
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
    put:
      tags:
      - Branching model
      description: "Update the branching model configuration for a repository.\n\nThe `development` branch can be configured to a specific branch or to\ntrack the main branch. When set to a specific branch it must\ncurrently exist. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. A request without a\n`development` property will leave the development branch unchanged.\n\nIt is possible for the `development` branch to be invalid. This\nhappens when it points at a specific branch that has been\ndeleted. This is indicated in the `is_valid` field for the branch. It is\nnot possible to update the settings for `development` if that\nwould leave the branch in an invalid state. Such a request will be\nrejected.\n\nThe `production` branch can be a specific branch, the main\nbranch or disabled. When set to a specific branch it must currently\nexist. The `enabled` property can be used to enable (`true`) or\ndisable (`false`) it. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. A request without a\n`production` property will leave the production branch unchanged.\n\nIt is possible for the `production` branch to be invalid. This\nhappens when it points at a specific branch that has been\ndeleted. This is indicated in the `is_valid` field for the branch. A\nrequest that would leave `production` enabled and invalid will be\nrejected. It is possible to update `production` and make it invalid if\nit would also be left disabled.\n\nThe `branch_types` property contains the branch types to be updated.\nOnly the branch types passed will be updated. All updates will be\nrejected if it would leave the branching model in an invalid state.\nFor branch types this means that:\n\n1. The prefixes for all enabled branch types are valid. For example,\n   it is not possible to use '*' inside a Git prefix.\n2. A prefix of an enabled branch type must not be a prefix of another\n   enabled branch type. This is to ensure that a branch can be easily\n   classified by its prefix unambiguously.\n\nIt is possible to store an invalid prefix if that branch type would be\nleft disabled. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. Each branch type must\nhave a `kind` property to identify it.\n\nThe `default_branch_deletion` property is a string. The value of `true`\nindicates to delete branches by default. The value of `false` indicates\nthat branches will not be deleted by default. A request without a\n`default_branch_deletion` property will leave it unchanged. Other values\nwould be ignored.\n\nThere is currently a side effect when using this API endpoint. If the\nrepository is inheriting branching model settings from its project,\nupdating the branching model for this repository will disable the\nproject setting inheritance.\n\n\nWe have deprecated this side effect and will remove it on 1 August 2022."
      summary: Update the branching model config for a repository
      responses:
        '200':
          description: The updated branching model configuration
          schema:
            $ref: '#/definitions/branching_model_settings'
          examples:
            application/json:
              development:
                use_mainbranch: true
              production:
                enabled: true
                use_mainbranch: false
                name: production
              branch_types:
              - kind: bugfix
                enabled: true
                prefix: bugfix/
              - kind: feature
                enabled: true
                prefix: feature/
              - kind: hotfix
                prefix: hotfix/
              - kind: release
                enabled: false
              default_branch_deletion: 'true'
        '400':
          description: If the request contains invalid branching model configuration
          schema:
            $ref: '#/definitions/error'
        '401':
          description: If the request was not authenticated
          schema:
            $ref: '#/definitions/error'
        '403':
          description: If the authenticated user does not have admin access to the repository
          schema:
            $ref: '#/definitions/error'
        '404':
          description: If the repository does not exist
          schema:
            $ref: '#/definitions/error'
      parameters: []
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:repository:bitbucket
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
  /repositories/{workspace}/{repo_slug}/effective-branching-model:
    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
      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
      type: string
    get:
      tags:
      - Branching model
      description: ''
      summary: Get the effective, or currently applied, branching model for a repository
      responses:
        '200':
          description: The effective branching model object
          schema:
            $ref: '#/definitions/effective_repo_branching_model'
        '401':
          description: If the request was not authenticated
          schema:
            $ref: '#/definitions/error'
        '403':
          description: If the authenticated user does not have read access to the repository
          schema:
            $ref: '#/definitions/error'
        '404':
          description: If the repository does not exist
          schema:
            $ref: '#/definitions/error'
      parameters: []
      security:
      - oauth2:
        - repository
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
  /workspaces/{workspace}/projects/{project_key}/branching-model:
    parameters:
    - name: project_key
      in: path
      description: 'The project in question. This is the actual `key` assigned

        to the project.

        '
      required: true
      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
      type: string
    get:
      tags:
      - Branching model
      description: "Return the branching model set at the project level. This view is\nread-only. The branching model settings can be changed using the\n[settings](#api-workspaces-workspace-projects-project-key-branching-model-settings-get)\nAPI.\n\nThe returned object:\n\n1. Always has a `development` property. `development.name` is\n   the user-specified branch that can be inherited by an individual repository's\n   branching model.\n2. Might have a `production` property. `production` will not\n   be present when `production` is disabled.\n   `production.name` is the user-specified branch that can be\n   inherited by an individual repository's branching model.\n3. Always has a `branch_types` array which contains all enabled branch\n   types."
      summary: Get the branching model for a project
      responses:
        '200':
          description: The branching model object
          schema:
            $ref: '#/definitions/project_branching_model'
          examples:
            application/json:
              development:
                name: master
                use_mainbranch: true
              production:
                name: production
                use_mainbranch: false
              branch_types:
              - kind: release
                prefix: release/
              - kind: hotfix
                prefix: hotfix/
              - kind: feature
                prefix: feature/
              - kind: bugfix
                prefix: bugfix/
              type: project_branching_model
              links:
                self:
                  href: https://api.bitbucket.org/.../branching-model
        '401':
          description: If the request was not authenticated
          schema:
            $ref: '#/definitions/error'
        '403':
          description: If the authenticated user does not have read access to the project
          schema:
            $ref: '#/definitions/error'
        '404':
          description: If the project does not exist
          schema:
            $ref: '#/definitions/error'
      parameters: []
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:repository:bitbucket
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
  /workspaces/{workspace}/projects/{project_key}/branching-model/settings:
    parameters:
    - name: project_key
      in: path
      description: 'The project in question. This is the actual `key` assigned

        to the project.

        '
      required: true
      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
      type: string
    get:
      tags:
      - Branching model
      description: "Return the branching model configuration for a project. The returned\nobject:\n\n1. Always has a `development` property for the development branch.\n2. Always a `production` property for the production branch. The\n   production branch can be disabled.\n3. The `branch_types` contains all the branch types.\n4. `default_branch_deletion` indicates whether branches will be\n    deleted by default on merge.\n\n\nThis is the raw configuration for the branching model. A client\nwishing to see the branching model with its actual current branches may find the\n[active model API](#api-workspaces-workspace-projects-project-key-branching-model-get)\nmore useful."
      summary: Get the branching model config for a project
      responses:
        '200':
          description: The branching model configuration
          schema:
            $ref: '#/definitions/branching_model_settings'
          examples:
            application/json:
              development:
                name: 'null'
                use_mainbranch: true
              production:
                name: production
                use_mainbranch: false
                enabled: false
              branch_types:
              - kind: release
                enabled: true
                prefix: release/
              - kind: hotfix
                enabled: true
                prefix: hotfix/
              - kind: feature
                enabled: true
                prefix: feature/
              - kind: bugfix
                enabled: false
                prefix: bugfix/
              type: branching_model_settings
              links:
                self:
                  href: https://api.bitbucket.org/.../branching-model/settings
              default_branch_deletion: 'false'
        '401':
          description: If the request was not authenticated
          schema:
            $ref: '#/definitions/error'
        '403':
          description: If the authenticated user does not have admin access to the project
          schema:
            $ref: '#/definitions/error'
        '404':
          description: If the project does not exist
          schema:
            $ref: '#/definitions/error'
      parameters: []
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:project:bitbucket
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
    put:
      tags:
      - Branching model
      description: "Update the branching model configuration for a project.\n\nThe `development` branch can be configured to a specific branch or to\ntrack the main branch. Any branch name can be supplied, but will only\nsuccessfully be applied to a repository via inheritance if that branch\nexists for that repository. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. A request without a\n`development` property will leave the development branch unchanged.\n\nThe `production` branch can be a specific branch, the main\nbranch or disabled. Any branch name can be supplied, but will only\nsuccessfully be applied to a repository via inheritance if that branch\nexists for that repository. The `enabled` property can be used to enable (`true`)\nor disable (`false`) it. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. A request without a\n`production` property will leave the production branch unchanged.\n\nThe `branch_types` property contains the branch types to be updated.\nOnly the branch types passed will be updated. All updates will be\nrejected if it would leave the branching model in an invalid state.\nFor branch types this means that:\n\n1. The prefixes for all enabled branch types are valid. For example,\n   it is not possible to use '*' inside a Git prefix.\n2. A prefix of an enabled branch type must not be a prefix of another\n   enabled branch type. This is to ensure that a branch can be easily\n   classified by its prefix unambiguously.\n\nIt is possible to store an invalid prefix if that branch type would be\nleft disabled. Only the passed properties will be updated. The\nproperties not passed will be left unchanged. Each branch type must\nhave a `kind` property to identify it.\n\nThe `default_branch_deletion` property is a string. The value of `true`\nindicates to delete branches by default. The value of `false` indicates\nthat branches will not be deleted by default. A request without a\n`default_branch_deletion` property will leave it unchanged. Other values\nwould be ignored."
      summary: Update the branching model config for a project
      responses:
        '200':
          description: The updated branching model configuration
          schema:
            $ref: '#/definitions/branching_model_settings'
          examples:
            application/json:
              development:
                use_mainbranch: true
              production:
                enabled: true
                use_mainbranch: false
                name: production
              branch_types:
              - kind: bugfix
                enabled: true
                prefix: bugfix/
              - kind: feature
                enabled: true
                prefix: feature/
              - kind: hotfix
                prefix: hotfix/
              - kind: release
                enabled: false
              default_branch_deletion: 'false'
        '400':
          description: If the request contains an invalid branching model configuration
          schema:
            $ref: '#/definitions/error'
        '401':
          description: If the request was not authenticated
          schema:
            $ref: '#/definitions/error'
        '403':
          description: If the authenticated user does not have admin access to the project
          schema:
            $ref: '#/definitions/error'
        '404':
          description: If the project does not exist
          schema:
            $ref: '#/definitions/error'
      parameters: []
      security:
      - oauth2:
        - project:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:project:bitbucket
      x-atlassian-auth-types:
      - forge-oauth2
      - api-token
definitions:
  base_commit:
    allOf:
    - $ref: '#/definitions/object'
    - type: object
      title: Base Commit
      description: The common base type for both repository and snippet commits.
      properties:
        hash:
          type: string
          pattern: '[0-9a-f]{7,}?'
        date:
          type: string
          format: date-time
        author:
          $ref: '#/definitions/author'
        committer:
          $ref: '#/definitions/committer'
        message:
          type: string
        summary:
          type: object
          properties:
            raw:
              type: string
              description: The text as it was typed by a user.
            markup:
              type: string
              description: The type of markup language the raw content is to be interpreted in.
              enum:
              - markdown
              - creole
              - plaintext
            html:
              type: string
              description: The user's content rendered as HTML.
          additionalProperties: false
        parents:
          type: array
          items:
            $ref: '#/definitions/base_commit'
          minItems: 0
      additionalProperties: true
  effective_repo_branching_model:
    allOf:
    - $ref: '#/definitions/object'
    - type: object
      title: Effective Repository Branching Model
      description: A repository's effective branching model
      properties:
        branch_types:
          type: array
          description: The active branch types.
          items:
            type: object
            properties:
              kind:
                type: string
                description: The kind of branch.
                enum:
                - feature
                - bugfix
                - release
                - hotfix
              prefix:
                type: string
                description: The prefix for this branch type. A branch with this prefix will be classified as per `kind`. The prefix must be a valid prefix for a branch and must always exist. It cannot be blank, empty or `null`.
            required:
            - kind
            - prefix
            additionalProperties: false
          minItems: 0
          maxItems: 4
          uniqueItems: true
        development:
          type: object
          properties:
            branch:
              $ref: '#/definitions/branch'
            name:
              type: string
              description: Name of the target branch. Will be listed here even when the target branch does not exist. Will be `null` if targeting the main branch and the repository is empty.
            use_mainbranch:
              type: boolean
              description: Indicates if the setting points at an explicit branch (`false`) or tracks the main branch (`true`).
          required:
          - name
          - use_mainbranch
          additionalProperties: false
        production:
          type: object
          properties:
            branch:
              $ref: '#/definitions/branch'
            name:
              type: string
              description: Name of the target branch. Will be listed here even when the target branch does not exist. Will be `null` if targeting the main branch and the repository is empty.
            use_mainbranch:
              type: boolean
              description: Indicates if the setting points at an explicit branch (`false`) or tracks the main branch (`true`).
          required:
          - name
          - use_mainbranch
          additionalProperties: false
      additionalProperties: true
  repository:
    allOf:
    - $ref: '#/definitions/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: '#/definitions/repository'
        scm:
          type: string
          enum:
          - git
        owner:
          $ref: '#/definitions/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

# --- truncated at 32 KB (162 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitbucket/refs/heads/main/openapi/bitbucket-branching-model-api-openapi.yml