Atlassian Branching Model API

openapi: 3.2.0
info:
  title: Atlassian Bitbucket 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
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<br>read-only. The branching model settings can be changed using the<br>[settings](#api-repositories-workspace-repo-slug-branching-model-settings-get) API.<br><br>The returned object:<br><br>1. Always has a `development` property. `development.branch` contains<br>   the actual repository branch object that is considered to be the<br>   `development` branch. `development.branch` will not be present<br>   if it does not exist.<br>2. Might have a `production` property. `production` will not<br>   be present when `production` is disabled.<br>   `production.branch` contains the actual branch object that is<br>   considered to be the `production` branch. `production.branch` will<br>   not be present if it does not exist.<br>3. Always has a `branch_types` array which contains all enabled branch<br>   types.
      summary: Atlassian Get The Branching Model For A Repository
      responses:
        '200':
          description: The branching model object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model'
              examples:
                response:
                  value:
                    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
      operationId: atlassianGetTheBranchingModelForARepository
  /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<br>object:<br><br>1. Always has a `development` property for the development branch.<br>2. Always a `production` property for the production branch. The<br>   production branch can be disabled.<br>3. The `branch_types` contains all the branch types.<br><br>This is the raw configuration for the branching model. A client<br>wishing to see the branching model with its actual current branches may<br>find the [active model API](/cloud/bitbucket/rest/api-group-branching-model/#api-repositories-workspace-repo-slug-branching-model-get) more useful.
      summary: Atlassian 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'
              examples:
                response:
                  value:
                    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
        '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
      operationId: atlassianGetTheBranchingModelConfigForARepository
    put:
      tags:
      - Branching Model
      description: Update the branching model configuration for a repository.<br><br>The `development` branch can be configured to a specific branch or to<br>track the main branch. When set to a specific branch it must<br>currently exist. Only the passed properties will be updated. The<br>properties not passed will be left unchanged. A request without a<br>`development` property will leave the development branch unchanged.<br><br>It is possible for the `development` branch to be invalid. This<br>happens when it points at a specific branch that has been<br>deleted. This is indicated in the `is_valid` field for the branch. It is<br>not possible to update the settings for `development` if that<br>would leave the branch in an invalid state. Such a request will be<br>rejected.<br><br>The `production` branch can be a specific branch, the main<br>branch or disabled. When set to a specific branch it must currently<br>exist. The `enabled` property can be used to enable (`true`) or<br>disable (`false`) it. Only the passed properties will be updated. The<br>properties not passed will be left unchanged. A request without a<br>`production` property will leave the production branch unchanged.<br><br>It is possible for the `production` branch to be invalid. This<br>happens when it points at a specific branch that has been<br>deleted. This is indicated in the `is_valid` field for the branch. A<br>request that would leave `production` enabled and invalid will be<br>rejected. It is possible to update `production` and make it invalid if<br>it would also be left disabled.<br><br>The `branch_types` property contains the branch types to be updated.<br>Only the branch types passed will be updated. All updates will be<br>rejected if it would leave the branching model in an invalid state.<br>For branch types this means that:<br><br>1. The prefixes for all enabled branch types are valid. For example,<br>   it is not possible to use '*' inside a Git prefix.<br>2. A prefix of an enabled branch type must not be a prefix of another<br>   enabled branch type. This is to ensure that a branch can be easily<br>   classified by its prefix unambiguously.<br><br>It is possible to store an invalid prefix if that branch type would be<br>left disabled. Only the passed properties will be updated. The<br>properties not passed will be left unchanged. Each branch type must<br>have a `kind` property to identify it.<br><br>There is currently a side effect when using this API endpoint. If the<br>repository is inheriting branching model settings from its project,<br>updating the branching model for this repository will disable the<br>project setting inheritance.<br><br><br>We have deprecated this side effect and will remove it on 1 August 2022.
      summary: Atlassian 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'
              examples:
                response:
                  value:
                    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
        '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
      operationId: atlassianUpdateTheBranchingModelConfigForARepository
  /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: Needs a more full description created.
      summary: Atlassian 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
      operationId: atlassianGetTheEffective,OrCurrentlyApplied,BranchingModelForARepository
  /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<br>read-only. The branching model settings can be changed using the<br>[settings](#api-workspaces-workspace-projects-project-key-branching-model-settings-get)<br>API.<br><br>The returned object:<br><br>1. Always has a `development` property. `development.name` is<br>   the user-specified branch that can be inherited by an individual repository's<br>   branching model.<br>2. Might have a `production` property. `production` will not<br>   be present when `production` is disabled.<br>   `production.name` is the user-specified branch that can be<br>   inherited by an individual repository's branching model.<br>3. Always has a `branch_types` array which contains all enabled branch<br>   types.
      summary: Atlassian Get The Branching Model For A Project
      responses:
        '200':
          description: The branching model object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/project_branching_model'
              examples:
                response:
                  value:
                    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
      operationId: atlassianGetTheBranchingModelForAProject
  /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<br>object:<br><br>1. Always has a `development` property for the development branch.<br>2. Always a `production` property for the production branch. The<br>   production branch can be disabled.<br>3. The `branch_types` contains all the branch types.<br><br><br>This is the raw configuration for the branching model. A client<br>wishing to see the branching model with its actual current branches may find the<br>[active model API](#api-workspaces-workspace-projects-project-key-branching-model-get)<br>more useful.
      summary: Atlassian 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'
              examples:
                response:
                  value:
                    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
        '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
      operationId: atlassianGetTheBranchingModelConfigForAProject
    put:
      tags:
      - Branching Model
      description: Update the branching model configuration for a project.<br><br>The `development` branch can be configured to a specific branch or to<br>track the main branch. Any branch name can be supplied, but will only<br>successfully be applied to a repository via inheritance if that branch<br>exists for that repository. Only the passed properties will be updated. The<br>properties not passed will be left unchanged. A request without a<br>`development` property will leave the development branch unchanged.<br><br>The `production` branch can be a specific branch, the main<br>branch or disabled. Any branch name can be supplied, but will only<br>successfully be applied to a repository via inheritance if that branch<br>exists for that repository. The `enabled` property can be used to enable (`true`)<br>or disable (`false`) it. Only the passed properties will be updated. The<br>properties not passed will be left unchanged. A request without a<br>`production` property will leave the production branch unchanged.<br><br>The `branch_types` property contains the branch types to be updated.<br>Only the branch types passed will be updated. All updates will be<br>rejected if it would leave the branching model in an invalid state.<br>For branch types this means that:<br><br>1. The prefixes for all enabled branch types are valid. For example,<br>   it is not possible to use '*' inside a Git prefix.<br>2. A prefix of an enabled branch type must not be a prefix of another<br>   enabled branch type. This is to ensure that a branch can be easily<br>   classified by its prefix unambiguously.<br><br>It is possible to store an invalid prefix if that branch type would be<br>left disabled. Only the passed properties will be updated. The<br>properties not passed will be left unchanged. Each branch type must<br>have a `kind` property to identify it.
      summary: Atlassian 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'
              examples:
                response:
                  value:
                    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
        '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
      operationId: atlassianUpdateTheBranchingModelConfigForAProject
components:
  schemas:
    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'
        additionalProperties: true
    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

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