Atlassian Branching API

openapi: 3.1.0
info:
  title: Atlassian Admin Account Branching API
  description: The Atlassian Admin API provides programmatic access to manage Atlassian organizations, users, domains, policies, and events. It enables administrators to automate organization management tasks, integrate with identity providers, and ensure appropriate access to Atlassian products.
  version: 1.0.0
  contact:
    name: Atlassian Developer
    url: https://developer.atlassian.com/cloud/admin/
  license:
    name: Atlassian Developer Terms
    url: https://developer.atlassian.com/platform/marketplace/atlassian-developer-terms/
  x-logo:
    url: https://wac-cdn.atlassian.com/assets/img/favicons/atlassian/favicon.png
servers:
- url: https://api.atlassian.com
  description: Atlassian Cloud API
security:
- bearerAuth: []
- oauth2: []
tags:
- name: Branching
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
      description: This API operation retrieves the branching model configuration for a specific Bitbucket repository within a given workspace. By making a GET request to the endpoint with the appropriate workspace identifier and repository slug, it returns details about the repository's branching strategy, including information about production, development, and feature branch configurations, as well as any custom branch prefixes and patterns that have been defined. This is particularly useful for understanding how a team has structured their Git workflow, whether they're using Git Flow, trunk-based development, or a custom branching strategy, and helps developers and automation tools align with the repository's established branching conventions.
      summary: Atlassian Get the Branching Model for Repository
      responses:
        '200':
          description: The branching model object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model'
              examples:
                branching-model_2:
                  $ref: '#/components/examples/branching-model_2'
        '401':
          description: If the request was not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have 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: getTheBranchingModelForRepository
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
      description: This API operation retrieves the branching model configuration settings for a specific repository within an Atlassian Bitbucket workspace. By making a GET request to the endpoint with the workspace identifier and repository slug as path parameters, users can access the repository's configured branching strategy, which may include settings for development branches, production branches, branch prefixes, and other workflow-related configurations that govern how branches are created and managed within that repository. This information is useful for understanding the repository's branching conventions and automating branch creation processes according to the established model.
      summary: Atlassian Get the Branching Model Config for Repository
      responses:
        '200':
          description: The branching model configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model_settings'
              examples:
                branching-model-settings_2:
                  $ref: '#/components/examples/branching-model-settings_2'
        '401':
          description: If the request was not authenticated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: If the authenticated user does not have admin access to the repository
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the repository does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - repository:admin
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - admin:repository:bitbucket
      operationId: getTheBranchingModelConfigForRepository
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Branching
      description: This PUT operation updates the branching model configuration settings for a specific Bitbucket repository within a workspace. By sending a request to this endpoint with the workspace identifier and repository slug, administrators can modify how the repository handles branch types, naming conventions, and workflow patterns such as Git Flow or trunk-based development. The operation allows teams to enforce consistent branching strategies across their codebase by configuring settings for development branches, production branches, branch prefixes, and automated merge behaviors. This is particularly useful for organizations that want to standardize their Git workflow and ensure all team members follow the same branching conventions when creating feature branches, release branches, or hotfix branches within the repository.
      summary: Atlassian Update the Branching Model Config for Repository
      responses:
        '200':
          description: The updated branching model configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/branching_model_settings'
              examples:
                branching-model-settings_2:
                  $ref: '#/components/examples/branching-model-settings_2'
        '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: updateTheBranchingModelConfigForRepository
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
      description: This API operation retrieves the effective branching model currently applied to a specific Bitbucket repository within a given workspace. By providing the workspace identifier and repository slug as path parameters, it returns the active branching model configuration that governs how branches are organized and managed in that repository, including details about production branches, development branches, and any branch prefixes or patterns that are in use. This is particularly useful for understanding the workflow strategy implemented for the repository, whether it follows Git Flow, trunk-based development, or a custom branching strategy, and helps developers align their work with the established branch management conventions.
      summary: Atlassian Get the Effective, or Currently Applied, Branching Model for Repository
      responses:
        '200':
          description: The effective branching model object
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/effective_repo_branching_model'
              examples:
                effective-repository-branching-model:
                  $ref: '#/components/examples/effective-repository-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:repositoryBitbucket
      operationId: getTheEffective,OrCurrentlyApplied,BranchingModelForRepository
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
      description: This API operation retrieves the branching model configuration for a specific project within a Bitbucket workspace, allowing you to understand how branches are organized and managed within that project. By providing the workspace identifier and project key as path parameters, the GET request returns details about the project's branching strategy, which may include information about development branches, production branches, branch prefixes, and the overall workflow structure that defines how code changes flow from development to production. This is particularly useful for teams that want to programmatically access or audit their project's Git workflow configuration, integrate branching model information into CI/CD pipelines, or build custom tooling that needs to understand the project's branch organization scheme.
      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:
                project-branching-model:
                  $ref: '#/components/examples/project-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
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
      description: This API endpoint retrieves the branching model configuration settings for a specific project within a designated workspace in Atlassian Bitbucket. By making a GET request to this endpoint with the appropriate workspace identifier and project key, users can access the project's branching strategy configuration, which typically includes details about branch types, naming conventions, and workflow patterns such as Git Flow or similar branching models. This information helps teams understand and maintain consistent branching practices across their repositories within the project, ensuring standardized development workflows and version control strategies.
      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:
                branching-model-settings:
                  $ref: '#/components/examples/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
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      tags:
      - Branching
      description: This API operation updates the branching model configuration settings for a specific project within a Bitbucket workspace. It uses a PUT request to the endpoint /workspaces/{workspace}/projects/{project_key}/branching-model/settings, where you specify the workspace slug and project key as path parameters. The branching model defines the workflow for how branches are organized and managed in a project, including settings for development branches, production branches, and branch prefixes for features, releases, hotfixes, and bugfixes. By calling this endpoint, administrators can modify these configuration rules to align with their team's Git workflow strategy, such as Git Flow or a custom branching strategy, ensuring consistent branch naming conventions and automated branch type recognition across the project.
      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:
                branching-model-settings_2:
                  $ref: '#/components/examples/branching-model-settings_2_2'
        '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
      x-api-evangelist-processing:
        WriteDescription: true
        ChooseTags: true
        GenerateExampleFromOperationResponseSchema: true
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    account:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Account
        description: An account object.
        properties:
          links:
            $ref: '#/components/schemas/account_links'
          created_on:
            type: string
            format: date-time
          display_name:
            type: string
          username:
            type: string
            pattern: ^[a-zA-Z0-9_\-]+$
          uuid:
            type: string
        additionalProperties: true
    participant:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Participant
        description: Object describing a user's role on resources like commits or pull requests.
        properties:
          user:
            $ref: '#/components/schemas/account'
          role:
            type: string
            enum:
            - PARTICIPANT
            - REVIEWER
          approved:
            type: boolean
          state:
            type: string
            enum:
            - approved
            - changes_requested
            - null
          participated_on:
            type: string
            description: The ISO8601 timestamp of the participant's action. For approvers, this is the time of their approval. For commenters and pull request reviewers who are not approvers, this is the time they last commented, or null if they have not commented.
            format: date-time
        additionalProperties: true
    team_links:
      allOf:
      - $ref: '#/components/schemas/account_links'
      - type: object
        title: Team Links
        description: Links related to a Team.
        properties:
          self:
            $ref: '#/components/schemas/link'
          html:
            $ref: '#/components/schemas/link'
          members:
            $ref: '#/components/schemas/link'
          projects:
            $ref: '#/components/schemas/link'
          repositories:
            $ref: '#/components/schemas/link'
        additionalProperties: true
    project:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Project
        description: "A Bitbucket project.\n            Projects are used by teams to organize repositories."
        properties:
          links:
            type: object
            properties:
              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
            additionalProperties: false
          uuid:
            type: string
            description: The project's immutable id.
          key:
            type: string
            description: The project's key.
          owner:
            $ref: '#/components/schemas/team'
          name:
            type: string
            description: The name of the project.
          description:
            type: string
          is_private:
            type: boolean
            description: '

              Indicates whether the project is publicly accessible, or whether it is

              private to the team and consequently only visible to team members.

              Note that private projects cannot contain public repositories.'
          created_on:
            type: string
            format: date-time
          updated_on:
            type: string
            format: date-time
          has_publicly_visible_repos:
            type: boolean
            description: '

              Indicates whether the project contains publicly visible repositories.

              Note that private projects cannot contain public repositories.'
        additionalProperties: true
    error:
      type: object
      title: Error
      description: Base type for most resource objects. It defines the common `type` element that identifies an object's type. It also identifies the element as Swagger's `discriminator`.
      properties:
        type:
          type: string
          example: example_value
        error:
          type: object
          properties:
            message:
              type: string
            detail:
              type: string
            data:
              type: object
              description: Optional structured data that is endpoint-specific.
              properties: {}
              additionalProperties: true
          required:
          - message
          additionalProperties: false
          example: example_value
      required:
      - type
      additionalProperties: true
    author:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Author
        description: The author of a change in a repository
        properties:
          raw:
            type: string
            description: The raw author value from the repository. This may be the only value available if the author does not match a user in Bitbucket.
          user:
            $ref: '#/components/schemas/account'
        additionalProperties: true
    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
    team:
      allOf:
      - $ref: '#/components/schemas/account'
      - type: object
        title: Team
        description: A team object.
        properties:
          links:
            $ref: '#/components/schemas/team_links'
        additionalProperties: true
    branching_model:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Branching Model
        description: A repository'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:
              branch:
                $ref: '#/components/schemas/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: '#/components/schemas/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
    object:
      type: object
      description: Base type for most resource objects. It defines the common `type` element that identifies an object's type. It also identifies the element as Swagger's `discriminator`.
      properties:
        type:
          type: string
          example: example_value
      required:
      - type
      additionalProperties: true
      discriminator:
        propertyName: type
    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
          

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