openapi: "3.2.0"
info:
  title: Bump.sh Workspace 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
x-topics:
  - title: Authentication
    content:
      $ref: ./authentication.md
    example:
      $ref: ./authentication-example.md
tags:
  - name: Branches
    description: |
      Manage branches of a given documentation
    externalDocs:
      url: https://docs.bump.sh/help/branching
  - name: Diffs
  - name: Hubs
  - name: Ping
  - name: Previews
  - name: Versions
  - name: Validations
  - name: "Documentation change"
  - name: MCP servers
paths:
  /diffs:
    post:
      tags: [Diffs]
      summary: Create a diff
      description: |
        Create a diff between any two given API definitions.

        The diff result will be available asynchronously and needs
        to be retrieved with the [`GET /diffs/:id` API endpoint](#operation-get-diffs-parameter).
      security: []
      requestBody:
        $ref: "#/components/requestBodies/Diff"
      responses:
        "201":
          summary: "Diff successfully created"
          content:
            "application/json":
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: "Unique id of your diff"
                    example: d6f00a51-a175-4a44-a0c7-df62a48548ca
        "422":
          $ref: "#/components/responses/InvalidDefinition"
  /diffs/{id}:
    get:
      tags: [Diffs]
      summary: Fetch detailed information from an existing diff
      description: |
        Fetch the result of a previously created diff with the
        [`POST /diffs` API endpoint](#operation-post-diffs).
      security: []
      parameters:
        - in: path
          name: id
          schema:
            type: string
            description: UUID of an existing diff
          required: true
          description: UUID of an existing diff from which to fetch diff details
        - in: query
          name: formats
          description: |
            A list of formats to render in the response. Possible
            values are `text`, `markdown`, `html` or `json`. If not
            provided defaults to render both `text` and `markdown`
            formats.
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          summary: "Diff successfully retrieved"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/DiffForApi"
              examples:
                default:
                  $ref: "#/components/examples/DefaultDiff"
                html:
                  $ref: "#/components/examples/HTMLDiff"
                json:
                  $ref: "#/components/examples/JSONDiff"
        "202":
          description: "Diff is still being processed. Please try again later"
        "404":
          description: "Diff not found"
  /hubs:
    get:
      operationId: listHubs
      tags: [Hubs]
      summary: List all hubs
      security:
        - "Authorization token": []
      description: |
        List all hubs belonging to the authenticated organization.
        The API key used to make the request must be set at the organization level.
      responses:
        "200":
          summary: "Hubs successfully retrieved"
          content:
            "application/json":
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Hub"
        "401":
          description: "Unauthorized"
  /hubs/{hub_id_or_slug}:
    get:
      tags: [Hubs]
      summary: Fetch information of an existing Hub
      description: |
        Fetch information of an existing Hub including the list of
        APIs it contains. The response follows the [APIs.json
        specification](http://apisjson.org/).
      parameters:
        - in: path
          name: hub_id_or_slug
          schema:
            type: string
            description: UUID or slug of a Hub
          required: true
          description: UUID or slug of a Hub which can be Automatic Deployment settings page of your hub
      responses:
        "200":
          summary: "Hub successfully retrieved"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/HubWithApis"
        "400":
          summary: "Bad request"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ErrorDisabledOwner"
        "404":
          summary: "Hub not found"
  /versions:
    post:
      tags: [Versions]
      summary: Create a new version
      description: >
        Deploy a new version for a given documentation, which will become the current version.
      requestBody:
        $ref: "#/components/requestBodies/Version"
      responses:
        "201":
          summary: "Documentation version successfully created"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Version"
        "204":
          description: "Documentation is unchanged"
        "400":
          description: "Bad request"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ErrorDisabledOwner"
        "422":
          $ref: "#/components/responses/InvalidDefinition"
  /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"
  /validations:
    post:
      tags: [Validations]
      summary: Validate a documentation definition
      description: >
        Validate a definition against its schema (OpenAPI or AsyncAPI) and return errors without
        creating a new version. This is useful in a CI process, to validate that a changed
        definition file is valid and won't fail when being deployed on Bump.sh.
      security:
        - {}
        - "Authorization token": []
        - "Basic token": []
      requestBody:
        $ref: "#/components/requestBodies/Validate"
      responses:
        "200":
          summary: "Success"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Validation"
        "400":
          summary: "Bad request"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ErrorDisabledOwner"
        "422":
          $ref: "#/components/responses/InvalidDefinition"
  /previews:
    post:
      tags: [Previews]
      summary: Create a preview
      description: >
        Create a preview for a given documentation file. The preview will have a unique
        temporary URL, and will be active for 30 minutes.
      security: []
      requestBody:
        $ref: "#/components/requestBodies/Preview"
      responses:
        "201":
          summary: "Success"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Preview"
        "422":
          $ref: "#/components/responses/InvalidDefinition"
  /previews/{preview_id}:
    put:
      tags: [Previews]
      summary: Update an existing preview
      description: >
        Update a preview with the given documentation file. The preview will stay active for 30 minutes after the last update.
      security: []
      parameters:
        - in: path
          name: preview_id
          schema:
            type: string
          required: true
          description: UUID of an existing preview you wish to update.
      requestBody:
        $ref: "#/components/requestBodies/Preview"
      responses:
        "200":
          summary: "Success"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Preview"
        "422":
          $ref: "#/components/responses/InvalidDefinition"
  /versions/{version_id}:
    get:
      tags: [Versions]
      summary: Fetch a full documentation version including diff summary
      description: >
        Fetch a full documentation version including diff summary.
      parameters:
        - in: path
          name: version_id
          schema:
            type: string
            description: UUID of an existing documentation version.
          required: true
          description: UUID of an existing version from which to fetch a documentation change
        - in: query
          name: formats
          description: |
            A list of formats to render in the response. Possible
            values are `text`, `markdown`, `html` or `json`. If not
            provided defaults to render both `text`, `markdown` and
            `json` formats.
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          summary: "Success"
          content:
            "application/json":
              schema:
                allOf:
                  - $ref: "#/components/schemas/Version"
                  - $ref: "#/components/schemas/WithDiff"
        "202":
          summary: "Documentation version is still being processed. Please try again later"
        "400":
          summary: "Bad request"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/ErrorDisabledOwner"
        "404":
          description: "Version not found"
  /ping:
    get:
      tags: [Ping]
      summary: Check the API status
      description: Responds a pong if the API is up and running.
      security: []
      responses:
        "200":
          summary: "Success"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Pong"
        default:
          summary: API is currently down
  /mcp-servers/{mcp_server_id_or_slug}/deploy:
    post:
      tags:
      - MCP servers
      x-beta: true
      summary: Deploy a new MCP server document
      operationId: MCPServerDeploy
      description: >
        Deploy a new workflow document for a given MCP server.
      externalDocs:
        description: Learn more about MCP servers
        url: https://docs.bump.sh/help/mcp-servers/
      security:
        - "Authorization token": []
      parameters:
        - in: path
          name: mcp_server_id_or_slug
          schema:
            type: string
          required: true
          example: holiday-booking
          description: UUID or slug of a MCP server
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - definition
              properties:
                definition:
                  type: string
                  description: Workflow definition of the MCP server.
                  example: |
                    {"flower": "0.1", "title": "About crabs"}
                references:
                  type: array
                  description: |
                    List of external references required for Arazzo workflow documents (_aka_ API sources definitions following the OpenAPI specification).
                    More details about Arazzo and `sourcesDescriptions` in the [Arazzo documentation](https://docs.bump.sh/arazzo/v1.0/).
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        example: "firstSource"
                      content:
                        type: string
                        example: "{openapi: 3.0.0, title: My first Source}"
                      location:
                        type: string
                        example: "./openapi/first-source.yml"
      responses:
        "201":
          summary: "MCP server workflow document successfully deployed"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/WorkflowDocument"
        "204":
          summary: "MCP server workflow document already exists"
        "422":
          summary: "Invalid MCP server deployment request"
          content:
            "application/json":
              schema:
                $ref: "#/components/schemas/Error"

webhooks:
  DocStructureChange:
    post:
      tags: ["Documentation change"]
      operationId: webhookDocStructureChange
      summary: Structure change
      description: Payload sent when your documentation receives a deployment with a structure change.
      security: []
      parameters:
        - name: X_BUMP_SIGNATURE_256
          in: header
          description: The hash signature of the payload. Bump.sh uses a HMAC hex digest (SHA256) to compute the signature of the body payload with the webhook secret. More info in help.
          example: a0b1c1d2e3f5a8b13c21d34e55f89a144b233c377d610e987f1597a2584b4181
          required: true
          schema:
            type: string
      requestBody:
        description: Information about last documentation structure change of your API history
        content:
          application/json:
            schema:
              type: object
              required:
                - api
                - diff
              properties:
                api:
                  description: Details of the affected API
                  $ref: "#/components/schemas/Api"
                diff:
                  description: Details of the documentation change
                  $ref: "#/components/schemas/Diff"

security:
  - "Authorization token": []
  - "Basic token": []
components:
  securitySchemes:
    "Authorization token":
      type: http
      scheme: token
    "Basic token":
      type: http
      scheme: basic
      deprecated: true
  requestBodies:
    Branch:
      description: The branch creation request object
      content:
        "application/json":
          schema:
            $ref: "#/components/schemas/BranchRequest"
    Diff:
      description: The diff creation request object
      content:
        "application/json":
          schema:
            $ref: "#/components/schemas/DiffRequest"
    Preview:
      description: The preview creation request object
      content:
        "application/json":
          schema:
            $ref: "#/components/schemas/Preview"
    Validate:
      description: The version validation request object
      content:
        "application/json":
          schema:
            allOf:
              - $ref: "#/components/schemas/DocumentationRequest"
              - $ref: "#/components/schemas/Preview"

    Version:
      description: The version creation request object
      content:
        "application/json":
          schema:
            allOf:
              - $ref: "#/components/schemas/DocumentationRequest"
              - $ref: "#/components/schemas/VersionRequest"
              - type: object
                properties:
                  previous_version_id:
                    type: string
                    description: UUID of a previously deployed version
                    example: 3ef8f52f-9056-4113-840e-2f7183b90e06
                  temporary:
                    type: boolean
                    description: Whether you want the new version to be temporary or not. By default a new version will be permanent to your documentation. Temporary versions have a time to live of 7 days after which they are removed.
                    example: false
                  unpublished:
                    type: boolean
                    description: Alias for temporary property.
                    deprecated: true
                    example: false
          examples:
            default:
              $ref: "#/components/examples/NewVersion/ExistingDocumentation"
            auto_create_standalone:
              $ref: "#/components/examples/NewVersion/CreatingStandaloneDocumentation"
            auto_create_in_hub:
              $ref: "#/components/examples/NewVersion/CreatingDocumentationInHub"

  responses:
    "InvalidDefinition":
      summary: Definition is not valid.
      content:
        "application/json":
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Hub:
      type: object
      properties:
        id:
          type: string
          description: UUID of this Hub
          example: 3ef8f52f-9056-4113-840e-2f7183b90e06
        name:
          type: string
          description: The name of the Hub
          example: My train company hub
        description:
          type: string
          description: The description of the Hub
          example: |
            # Welcome to my train company

            This hub contains all APIs belonging to [my train company](https://demo.bump.sh/).
            Feel free to visit the documentation or changes of our APIs lifecycle.
        url:
          type: string
          description: The public URL of the hub
          example: https://demo.bump.sh/
        created:
          type: string
          format: date
          description: Creation date of this Hub
          example: "2022-01-07"
        modified:
          type: string
          format: date
          description: Last udpate date of this Hub
          example: "2022-04-07"
        specificationVersion:
          type: string
          description: |
            version of the [APIs.json
            specification](http://apisjson.org/) specification in use.
          example: "0.16"
    HubWithApis:
      allOf:
        - $ref: "#/components/schemas/Hub"
        - type: object
          properties:
            apis:
              type: array
              description: The list of APIs belonging to this Hub
              items:
                $ref: "#/components/schemas/Api"
    Api:
      type: object
      properties:
        id:
          type: string
          description: UUID of this API
          example: 3ef8f52f-9056-4113-840e-2f7183b90e06
        name:
          type: string
          description: Name of this API
          example: Bump.sh
        description:
          type: string
          description: Description of this API from the latest definition
          example: This is the official Bump.sh API documentation. Obviously created with Bump.sh
        slug:
          type: string
          description: Slug of this API
          example: bump
        url:
          type: string
          deprecated: true
        humanUrl:
          type: string
          description: public documentation URL
          example: https://developers.bump.sh/doc/workspace/
        tags:
          type: array
          items:
            type: string
          description: a list of descriptive strings which identify the API within a Hub
        version:
          type: string
          description: Version of this API taken from the latest definition
          example: "1.0"
        properties:
          type: array
          description: Extra properties attached to this API
          items:
            type: object
            properties:
              type:
                type: string
                description: Type of the extra property
                enum:
                  - "OpenAPI"
                  - "AsyncAPI"
                  - "x-access-level"
                  - "x-definition-type"
              data:
                type: string
                description: Content of the extra property (`data` or `url`)
              url:
                type: string
                description: Content of the extra property (`data` or `url`)
            example:
              type: "OpenAPI"
              url: "https://developers.bump.sh/doc/workspace/source.json"
        created:
          type: date
          description: Creation date of this API
          example: "2022-01-07"
        modified:
          type: date
          description: Last udpate date of this API
          example: "2022-04-07"
    Reference:
      type: object
      properties:
        location:
          type: string
          description: Location of the external reference as it's called from `definition`, without the relative path (the part after `#/`). Can be an URL of a file system path.
          example: https://example.com/api/models/pet.yml
        content:
          type: string
          description: Content of the external reference, as a string.
    Error:
      properties:
        message:
          type: string
          description: Human readable error message.
          example: Invalid definition file
        errors:
          type: object
          description: Hash of invalid attributes with their error messages.
          example:
            raw_definition:
              - The property '#/paths//docs/{:id}/validations/post' contains additional properties ["yolo"] outside of the schema when none are allowed
    ErrorDisabledOwner:
      properties:
        message:
          type: string
          description: Human readable error message for status 400.
          example: "You need to upgrade your subscription plan to perform this request."

    Pong:
      properties:
        pong:
          type: string
          description: Sentence about ping and pong
          example: And that's how ping-pong ball is bumped
    Version:
      properties:
        id:
          type: string
          description: "Unique id of your version."
          example: 2361df99-3467-4c80-a0cc-45c9fe565812
        doc_id:
          type: string
          description: "Unique id of your documentation."
          example: 3ef8f52f-9056-4113-840e-2f7183b90e06
        doc_public_url:
          type: string
          description: "The public URL of your documentation."
          example: https://bump.sh/doc/my-own-documentation
    WithDiff:
      properties:
        diff_details:
          type: array
          description: "Details of each change as a list of diff items"
          items:
            $ref: "#/components/schemas/DiffItem"
        diff_markdown:
          type: string
          description: "The comparaison diff summary in markdown format"
          example: |
            ## Modified (1)

            * `POST /user`
              * Path parameters added: `id`, `email`
              * Query parameters added: `period`, `limit`
        diff_summary:
          type: string
          description: "The comparaison diff summary"
          example: |
            Updated: POST /versions
              Response modified: 201
                Body attribute added: doc_id
        diff_public_url:
          type: string
          description: "The public URL of your diff"
          example: https://bump.sh/doc/my-own-documentation/change/2361df99-3467-4c80-a0cc-45c9fe565812
        diff_breaking:
          type: boolean
          description: Identifies if the diff includes breaking changes
          example: false
    Diff:
      type: object
      properties:
        id:
          type: string
          description: "Unique id of your diff"
          example: 2361df99-1234-4c80-a0cc-45c9fe565812
        title:
          type: string
          description: "The title of the last parsed definition"
          example: "Bump.sh Api"
        public_url:
          type: string
          description: "The public URL of your diff"
          example: https://bump.sh/doc/my-own-documentation/change/2361df99
        breaking:
          type: boolean
          description: Identifies if the diff includes breaking changes
          example: false
        details:
          type: array
          description: "Details of each change as a list of diff items. Present only if `json` format has been requested"
          items:
            $ref: "#/components/schemas/DiffItem"
        previous_version_url:
          type: string
          description: URL of previous version specification, in JSON format
          example: https://developers.bump.sh/doc/workspace/changes/750f15d8/previous.json
        current_version_url:
          type: string
          description: URL of current version specification, in JSON format
          example: https://developers.bump.sh/doc/workspace/changes/750f15d8/current.json
    DiffItem:
      properties:
        id:
          type: string
          description: "The identifier of the diff change"
          example: "post-versions"
        name:
          type: string
          description: "The human name of diff change"
          example: "POST /versions"
        status:
          type: string
          enum:
            - added
            - modified
            - removed
          example: modified
        type:
          type: string
          description: "The object type of the diff change"
          example: "endpoint"
        breaking:
          type: boolean
          description: Identifies if the item is a breaking change
          example: true
        previous:
          type: object
          description: Object attributes values, before change. Possible attributes depend on the object `type` ('endpoint', 'body', 'response'…)
          example:
            path: "/versions"
            deprecated: false
            verb: POST
        current:
          type: object
          description: Object attributes values, after change. Possible attributes depend on the object `type` ('property', 'operation', 'message'…)
          example:
            path: "/version"
            deprecated: false
            verb: PUT
        breaking_details:
          type: object
          description: |
            Represents breaking change reasons, used to give more
            context about this question: _why is this change
            breaking?_
          properties:
            message_key:
              type: string
              description: This property is used to generate the human message about breaking change reason
              example: removed_not_deprecated
            breaking_attributes:
              type: array
              description: |
                When diff status is modified, this property is an
                array including every modified attribute responsible
                of the breaking change.
              items:
                type: string
              example: [verb, path]
        children:
          type: array
          description: A list of children item changes
          items:
            $ref: "#/components/schemas/DiffItem"
    DiffForApi:
      allOf:
        - $ref: "#/components/schemas/Diff"
        - type: object
          properties:
            markdown:
              type: string
              description: "The comparaison diff summary in markdown format. Present only if `markdown` format has been requested."
              example: |
                ## Modified (1)

                * `POST /user`
                  * Path parameters added: `id`, `email`
                  * Query parameters added: `period`, `limit`
            html:
              type: string
              description: "The comparaison diff summary in HTML format. Present only if `html` format has been requested."
              example: |
                <ul class="changelog-event__diff expandable" data-expander-target="content">
                    <li class="changelog-event__diff-operation added">
                         Added: <a href="http://localhost:3000/diff/c1e36203-5b04-4adc-b8c5-8ac626ce8592#operation-get-diffs-parameter"><code class="code-inline root">GET /diffs/{id}</code></a>
                    </li>
                </ul>
            text:
              type: string
              description: "The comparaison diff summary in plain text format. Present only if `text` format has been requested."
              example: |
                Updated: POST /versions
                  Response modified: 201
                    Body attribute added: doc_id
    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.
    DocumentationRequest:
      type: object
      required:
        - documentation
      properties:
        documentation:
          type: string
          description: UUID or slug of the documentation.
          example: "0776d85d-e097-47c1-8c60-cb1190d11945"
        hub:
          type: string
          description: UUID or slug of the hub if the documentation is part of a hub.
          example: "my_hub_slug"
        documentation_name:
          type: string
          description: Name of the documentation to create. Used only if `auto_create_documentation` is set.
        auto_create_documentation:
          type: boolean
          default: false
          description: Create the documentation if it does not exist yet. Must be used with a `hub` and a `documentation`.
    Validation:
      properties:
        specification:
          type: string
          description: "Specification of the given definition as a path: `speficiation_name/specification_version/format`."
          enum:
            - openapi/v2/yaml
            - openapi/v2/json
            - openapi/v3/yaml
            - openapi/v3/json
            - asyncapi/v2/yaml
            - asyncapi/v2/json
          example: openapi/v3/json
    VersionRequest:
      type: object
      required:
        - definition
      properties:
        definition:
          type: string
          description: >
            Serialized definition of the version. This should be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file
            serialized as a string, in YAML or JSON.
          example: |
            {"openapi": "3.0", "info": { "title": … }}
        references:
          type: array
          description: Import external references used by `definition`. It's usually resources not accessible by Bump.sh servers, like local files or internal URLs.
          items:
            $ref: "#/components/schemas/Reference"
        branch_name:
          type: string
          description: |
            Select a branch for this new version (branch will be
            created if it doesn't exist).

            *Defaults to the main branch*.
    Preview:
      type: object
      properties:
        definition:
          writeOnly: true
          type: string
          description: |
            <small>==**REQUIRED**==</small> if `url` is not present.

            Serialized definition. This should be an OpenAPI 2.x, 3.x
            or AsyncAPI 2.x file serialized as a string, in YAML or
            JSON.
          example: |
            {"openapi": "3.0", "info": { "title": … }}
        references:
          writeOnly: true
          type: array
          description: Import external references used by `definition`. It's usually resources not accessible by Bump.sh servers, like local files or internal URLs.
          items:
            $ref: "#/components/schemas/Reference"
        url:
          writeOnly: true
          type: string
          format: uri
          description: |
            <small>==**REQUIRED**==</small> if `definition` is not present.

            Target definition URL. It should be accessible through
            HTTP by Bump.sh servers.
        id:
          readOnly: true
          type: string
          description: "Unique id for the preview URL: `https://bump.sh/preview/:id`."
          example: 3ef8f52f-9056-4113-840e-2f7183b90e06
        expires_at:
          readOnly: true
          type: string
          format: date-time
          description: Preview expiration date and time.
          example: 2010-04-14T17:05:00+01:00
        public_url:
          readOnly: true
          type: string
          description: "The public URL where the preview will be visible."
          example: https://bump.sh/preview/3ef8f52f-9056-4113-840e-2f7183b90e06
    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
    DiffRequest:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: |
            <small>==**REQUIRED**==</small> if `definition` is not present.

            Current definition URL. It should be accessible through
            HTTP by Bump.sh servers.
        previous_url:
          type: string
          format: uri
          description: |
            <small>==**REQUIRED**==</small> if `definition` is not present.

            Previous definition URL. It should be accessible through
            HTTP by Bump.sh servers.
        previous_definition:
          type: string
          description: |
            <small>==**REQUIRED**==</small> if `url` is not present.

            Serialized definition of the previous version. This should
            be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file serialized as
            a string, in YAML or JSON.
          example: |
            {"openapi": "3.0", "info": { "title": … }}
        previous_references:
          type: array
          description: Import external references used by `previous_definition`. It's usually resources not accessible by Bump.sh servers, like local files or internal URLs.
          items:
            $ref: "#/components/schemas/Reference"
        definition:
          type: string
          description: |
            <small>==**REQUIRED**==</small> if `url` is not present.

            Serialized definition of the current version. This should
            be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file serialized as
            a string, in YAML or JSON.
          example: |
            {"openapi": "3.0", "info": { "title": … }}
        references:
          type: array
          description: Import external references used by `definition`. It's usually resources not accessible by Bump.sh servers, like local files or internal URLs.
          items:
            $ref: "#/components/schemas/Reference"
        expires_at:
          type: string
          format: date-time
          description: Public change expiration date and time. After this date, this documentation change will be destroyed.
          example: 2022-02-22T22:20:22.020Z
    WorkflowDocument:
      type: object
      properties:
        id:
          type: string
          description: UUID of the workflow deployment
        mcp_server_id:
          type: string
          description: UUID of the MCP server

  examples:
    CommonDiff:
      summary: "No formats"
      value: &commonDiff
        id: 2361df99-1234-4c80-a0cc-45c9fe565812
        public_url: https://bump.sh/diff/2361df99-3467-4c80-a0cc-45c9fe565812
        breaking: false
        previous_version_url: https://bump.sh/diff/2361df99-3467-4c80-a0cc-45c9fe565812/previous.json
        current_version_url: https://bump.sh/diff/2361df99-3467-4c80-a0cc-45c9fe565812/current.json
    DefaultDiff:
      summary: "Default response"
      value:
        <<: *commonDiff
        text: |
          Updated: POST /versions
            Response modified: 201
              Body attribute added: doc_id
        markdown: |
          ## Modified (1)

          * `POST /user`
            * Path parameters added: `id`, `email`
            * Query parameters added: `period`, `limit`
    HTMLDiff:
      summary: "HTML only response"
      value:
        <<: *commonDiff
        html: |
          <ul class="changelog-event__diff expandable" data-expander-target="content">
            <li class="changelog-event__diff-operation added">
               Added: <a href="http://localhost:3000/diff/c1e36203-5b04-4adc-b8c5-8ac626ce8592#operation-get-diffs-parameter"><code class="code-inline root">GET /diffs/{id}</code></a>
            </li>
          </ul>
    JSONDiff:
      summary: "JSON only response"
      value:
        <<: *commonDiff
        details:
          - id: "post-versions"
            name: "POST /versions"
            status: "added"
            type: "endpoint"
            breaking: false
            children: []
    NewVersion:
      ExistingDocumentation:
        summary: Create new version on an existing documentation
        value:
          definition: '{"openapi": "3.1.0", "info": { "title": … }}'
          references:
            - location: https://example.com/api/models/pet.yml
              content: string
          branch_name: dev
          documentation: my_api_slug
      CreatingStandaloneDocumentation:
        summary: Create a new standalone documentation with the given version
        value:
          definition: '{"openapi": "3.1.0", "info": { "title": … }}'
          references:
            - location: https://example.com/api/models/pet.yml
              content: string
          documentation: my_new_api_slug
          documentation_name: My new API documentation
          auto_create_documentation: true
      CreatingDocumentationInHub:
        summary: Create a new documentation inside a hub
        value:
          definition: '{"openapi": "3.1.0", "info": { "title": … }}'
          references:
            - location: https://example.com/api/models/pet.yml
              content: string
          documentation: my_new_api_slug
          documentation_name: My new API documentation
          auto_create_documentation: true
          hub: my_hub_slug