Bitbucket Branching model API

openapi: 3.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
servers:
- url: https://api.bitbucket.org/2.0
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
      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:
      - 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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model'
              example:
                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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have read 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'
      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
      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:
      - 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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model_settings'
              example:
                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
          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'
      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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model_settings'
              example:
                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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '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'
      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
      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:
      - Branching model
      description: ''
      summary: Get the effective, or currently applied, branching model for a repository
      responses:
        '200':
          description: The effective branching model object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/effective_repo_branching_model'
        '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 read 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'
      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
      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:
      - 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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project_branching_model'
              example:
                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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have read access to the project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the project does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      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
      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:
      - 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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model_settings'
              example:
                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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have admin access to the project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the project does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model_settings'
              example:
                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
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '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 project
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the project does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      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
components:
  schemas:
    ref:
      type: object
      title: Ref
      description: A ref object, representing a branch or tag in a repository.
      properties:
        type:
          type: string
        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
            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
            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
        name:
          type: string
          description: The name of the ref.
        target:
          $ref: '#/components/schemas/commit'
      required:
      - type
      additionalProperties: true
    commit:
      allOf:
      - $ref: '#/components/schemas/base_commit'
      - type: object
        title: Commit
        description: A repository commit object.
        properties:
          repository:
            $ref: '#/components/schemas/repository'
          participants:
            type: array
            items:
              $ref: '#/components/schemas/participant'
            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
      required:
      - type
      additionalProperties: true
      discriminator:
        propertyName: type
    project_branching_model:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Project Branching Model
        description: A project's 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:
              name:
                type: string
                description: Name of the target branch. If inherited by a repository, it will default to the main branch if the specified branch does not exist.
              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:
              name:
                type: string
                description: Name of the target branch. If inherited by a repository, it will default to the main branch if the specified branch does not exist.
              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
    branching_model_settings:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Branching Model Settings
        description: A repository's branching model settings
        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
          branch_types:
            type: array
            items:
              type: object
              properties:
                enabled:
                  type: boolean
                  description: Whether the branch type is enabled or not. A disabled branch type may contain an invalid `prefix`.
                kind:
                  type: string
                  description: The kind of the branch type.
                  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` of an enabled branch type must be a valid branch prefix.Additionally, it cannot be blank, empty or `null`. The `prefix` for a disabled branch type can be empty or invalid.
              required:
              - kind
              additionalProperties: false
            minItems: 0
            maxItems: 4
            uniqueItems: true
          development:
            type: object
            properties:
              is_valid:
                type: boolean
                description: Indicates if the configured branch is valid, that is, if the configured branch actua

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