openapi: 3.2.0
info:
  title: Bump.sh Api Branches API
  description: 'This is the official Bump.sh API documentation.  Obviously created

    with Bump.sh.


    The Bump.sh API is a REST API. It enables you to [create, update](#operation-post-versions)

    or [preview](#operation-post-previews) your API(s) documentation,

    [create stand-alone documentation diffs](#operation-post-diffs) or

    [validate a documentation definition](#operation-post-validations)

    (currently in OpenAPI or AsyncAPI).


    Our [webhook](#webhook-documentation-change) also lets you get

    notifications every time a change is introduced in your API.

    '
  version: '1.0'
servers:
- url: https://bump.sh/api/v1
  name: Production
security:
- Authorization token: []
- Basic token: []
tags:
- name: Branches
  description: 'Manage branches of a given documentation

    '
  externalDocs:
    url: https://docs.bump.sh/help/branching
paths:
  /docs/{doc_id_or_slug}/branches/{slug}/set_default:
    patch:
      tags:
      - Branches
      summary: Promote Branch as the Default One
      parameters:
      - in: path
        name: doc_id_or_slug
        schema:
          type: string
          description: UUID or slug of a documentation
        required: true
        description: UUID or slug of a documentation which can be seen in the Automatic Deployment settings page of your documentation
      - in: path
        name: slug
        schema:
          type: string
          description: Slug of a branch
          example: my-branch
        required: true
        description: Slug of a branch which can be seen in the branches settings page of your documentation
      responses:
        '200':
          summary: Branch is already the default branch.
        '204':
          summary: Branch is now set to default.
        '404':
          summary: Branch not found
        '422':
          summary: Branch has an empty history
  /docs/{doc_id_or_slug}/branches/{slug}:
    delete:
      tags:
      - Branches
      summary: Delete a Branch
      parameters:
      - in: path
        name: doc_id_or_slug
        schema:
          type: string
          description: UUID or slug of a documentation
        required: true
        description: UUID or slug of a documentation which can be seen in the Automatic Deployment settings page of your documentation
      - in: path
        name: slug
        schema:
          type: string
          example: my-branch
          description: Slug of a branch
        required: true
        description: Slug of a branch which can be seen in the branches settings page of your documentation
      responses:
        '204':
          summary: Branch successfully deleted
        '422':
          summary: The default branch can't be deleted
        '404':
          summary: Branch not found
  /docs/{doc_id_or_slug}/branches:
    get:
      tags:
      - Branches
      summary: List Available Branches
      description: 'List the available branches of a given documentation.

        '
      parameters:
      - in: path
        name: doc_id_or_slug
        schema:
          type: string
          description: UUID or slug of a documentation
        required: true
        description: UUID or slug of a documentation which can be seen in the Automatic Deployment settings page of your documentation
      responses:
        '200':
          summary: Array of existing branches
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Branch'
        '404':
          summary: Documentation does not exist
    post:
      tags:
      - Branches
      summary: Create a New Branch
      description: 'Create an empty new branch.

        '
      parameters:
      - in: path
        name: doc_id_or_slug
        schema:
          type: string
          description: UUID or slug of a documentation
        required: true
        description: UUID or slug of a documentation which can be seen in the Automatic Deployment settings page of your documentation
      requestBody:
        $ref: '#/components/requestBodies/Branch'
      responses:
        '201':
          summary: Documentation branch successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Branch'
        '204':
          summary: Branch already exists
        '422':
          summary: Invalid branch creation request
components:
  schemas:
    BranchRequest:
      type: object
      required:
      - name
      properties:
        name:
          type: string
          example: my-branch
          description: 'The name of the branch.


            > info

            > Please note that the branch name is used in

            > your documentation public URL

            '
    Branch:
      properties:
        name:
          type: string
          description: Unique id of the branch.
          example: 3ef8f52f-9056-4113-840e-2f7183b90e06
        slug:
          type: string
          description: Slug of the branch used in public documentation URL
          example: my-branch
        is_default:
          type: boolean
          default: false
          description: Whether the branch is the default one or not.
  requestBodies:
    Branch:
      description: The branch creation request object
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/BranchRequest'
  securitySchemes:
    Authorization token:
      type: http
      scheme: token
    Basic token:
      type: http
      scheme: basic
      deprecated: true
x-topics:
- title: Authentication
  content:
    $ref: ./authentication.md
  example:
    $ref: ./authentication-example.md