openapi: "3.1.0" info: title: Bump.sh 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 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: Ping - name: Previews - name: Versions - name: Validations - name: "Documentation change" 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": description: "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": description: "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/{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 CI deployment settings page of your hub responses: "200": description: "Hub successfully retrieved" content: "application/json": schema: $ref: "#/components/schemas/Hub" "400": description: "Bad request" content: "application/json": schema: $ref: "#/components/schemas/ErrorDisabledOwner" "404": description: "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": description: "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/{id_or_slug}/set_default: patch: tags: [ Branches ] summary: Promote branch as the default one parameters: - in: path name: doc_id 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 CI deployment settings page of your documentation - in: path name: slug schema: type: string description: UUID or slug of a branch required: true description: UUID or slug of a branch which can be seen in the branches settings page of your documentation responses: "204": description: "Branch is now set to default" "404": description: "Branch not found" /docs/{doc_id_or_slug}/branches/{id_or_slug}: delete: tags: [ Branches ] summary: Delete a branch parameters: - in: path name: doc_id 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 CI deployment settings page of your documentation - in: path name: slug schema: type: string description: UUID or slug of a branch required: true description: UUID or slug of a branch which can be seen in the branches settings page of your documentation responses: "204": description: "Branch successfully deleted" "422": description: "The default branch can't be deleted" "404": description: "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 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 CI deployment settings page of your documentation responses: "200": description: "Array of existing branches" content: "application/json": schema: type: array items: $ref: "#/components/schemas/Branch" "404": description: "Documentation does not exist" post: tags: [ Branches ] summary: Create a new branch description: | Create an empty new branch. parameters: - in: path name: doc_id 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 CI deployment settings page of your documentation requestBody: $ref: "#/components/requestBodies/Branch" responses: "201": description: "Documentation branch successfully created" content: "application/json": schema: $ref: "#/components/schemas/Branch" "204": description: "Branch already exists" "422": description: "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": description: "Success" content: "application/json": schema: $ref: "#/components/schemas/Validation" "400": description: "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": description: "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": description: "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 responses: "200": description: "Success" content: "application/json": schema: allOf: - $ref: "#/components/schemas/Version" - $ref: "#/components/schemas/WithDiff" "202": description: "Documentation version is still being processed. Please try again later" "400": description: "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": description: "Success" content: "application/json": schema: $ref: "#/components/schemas/Pong" default: description: API is currently down 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 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 object content: "application/json": schema: 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: | {asyncapi: "2.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" Validate: description: The version validation request object content: "application/json": schema: allOf: - $ref: "#/components/schemas/DocumentationRequest" - $ref: "#/components/schemas/PreviewRequest" 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. 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": description: Definition is not valid. content: "application/json": schema: $ref: "#/components/schemas/Error" schemas: Hub: type: object properties: 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: date description: Creation date of this Hub example: "2022-01-07" modified: type: date description: Last udpate date of this Hub example: "2022-04-07" 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 description: public documentation URL example: https://developers.bump.sh/ 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: - "x-access-level" - "x-definition-type" data: type: string description: Content of the extra property 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 to a paid plan to perform this request. Please go to https://bump.sh/account/billing" Pong: properties: pong: type: string description: Sentence about ping and pong example: And that's how ping-pong ball is bumped Preview: properties: id: type: string description: "Unique id for the preview URL: `https://bump.sh/preview/:id`." example: 3ef8f52f-9056-4113-840e-2f7183b90e06 expires_at: type: string format: date-time description: Preview expiration date and time. example: 2010-04-14T17:05:00+01:00 public_url: type: string description: "The public URL where the preview will be visible." example: https://bump.sh/preview/3ef8f52f-9056-4113-840e-2f7183b90e06 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-3467-4c80-a0cc-45c9fe565812 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/changes/750f15d8-6c41-47b9-8f80-e3ed812dbca9/previous.json current_version_url: type: string description: URL of current version specification, in JSON format example: https://developers.bump.sh/changes/750f15d8-6c41-47b9-8f80-e3ed812dbca9/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: | 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*. PreviewRequest: type: object properties: url: type: string format: uri description: | **Required** if [`definition`](#post-validations-definition) is not present. Target definition URL. It should be accessible through HTTP by Bump.sh servers. definition: type: string description: | **Required** if [`url`](#post-validations-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: 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" 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: | **Required** 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: | **Required** if `definition` is not present. Previous definition URL. It should be accessible through HTTP by Bump.sh servers. previous_definition: type: string description: | **Required** 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: | **Required** 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 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: | 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