This is the official Bump API documentation. Obviously created with Bump.
This is the documentation for version 1.0
of the API. Last update on May 12, 2022.
https://bump.sh/api/v1
This is the official Bump API documentation. Obviously created with Bump.
This is the documentation for version 1.0
of the API. Last update on May 12, 2022.
https://bump.sh/api/v1
This is the preferred authentication method for restricted access API endpoints
Use the token from your documentation settings in the HTTP token authorization header.
(Deprecated) Use the token from your documentation settings as the username of the basic auth, with no password.
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.
The diff creation request object
Required if definition
is not present.
Current definition URL. It should be accessible through HTTP by Bump servers..
Required if definition
is not present.
Previous definition URL. It should be accessible through HTTP by Bump servers..
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.
Import external references used by previous_definition
. It's usually resources not accessible by Bump servers, like local files or internal URLs.
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.
Import external references used by definition
. It's usually resources not accessible by Bump servers, like local files or internal URLs.
Public change expiration date and time. After this date, this documentation change will be destroyed.
curl \
-X POST https://bump.sh/api/v1/diffs \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","previous_url":"https://example.com","previous_definition":"{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n","previous_references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}],"definition":"{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}],"expires_at":"2022-02-22T22:20:22Z"}'
{
"url": "https://example.com",
"previous_url": "https://example.com",
"previous_definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n",
"previous_references": [
{
"location": "https://example.com/api/models/pet.yml",
"content": "string"
}
],
"definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n",
"references": [
{
"location": "https://example.com/api/models/pet.yml",
"content": "string"
}
],
"expires_at": "2022-02-22 22:20:22 UTC"
}
{
"id": "d6f00a51-a175-4a44-a0c7-df62a48548ca"
}
{
"message": "Invalid definition file",
"errors": {
"raw_definition": [
"The property '#/paths//docs/{:id}/validations/post' contains additional properties [\"yolo\"] outside of the schema when none are allowed"
]
}
}
Fetch the result of a previously created diff with the POST /diffs
API endpoint.
UUID of an existing diff from which to fetch diff details
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.
Diff successfully retrieved
Unique id of your diff
The title of the last parsed definition
The public URL of your diff
Identifies if the diff includes breaking changes
Details of each change as a list of diff items
URL of previous version specification, in JSON format
URL of current version specification, in JSON format
The comparaison diff summary in markdown format
The comparaison diff summary in HTML format
The comparaison diff summary in plain text format
Diff is still being processed. Please try again later
Diff not found
curl \
-X GET https://bump.sh/api/v1/diffs/{id}
{
"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",
"text": "Updated: POST /versions\n Response modified: 201\n Body attribute added: doc_id\n",
"markdown": "## Modified (1)\n\n* `POST /user`\n * Path parameters added: `id`, `email`\n * Query parameters added: `period`, `limit`\n"
}
{
"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",
"html": "<ul class=\"changelog-event__diff expandable\" data-expander-target=\"content\">\n <li class=\"changelog-event__diff-operation added\">\n 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>\n </li>\n</ul>\n"
}
{
"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",
"details": [
{
"id": "post-versions",
"name": "POST /versions",
"status": "added",
"type": "endpoint",
"breaking": false,
"children": []
}
]
}
curl \
-X GET https://bump.sh/api/v1/ping
{
"pong": "And that's how ping-pong ball is bumped"
}
Create a preview for a given documentation file. The preview will have a unique temporary URL, and will be active for 30 minutes.
The preview object
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.
Import external references used by definition
. It's usually resources not accessible by Bump servers, like local files or internal URLs.
Success
Unique id for the preview URL: https://bump.sh/preview/:id
.
Preview expiration date and time.
The public URL where the preview will be visible.
Definition is not valid.
curl \
-X POST https://bump.sh/api/v1/previews \
-H "Content-Type: application/json" \
-d '{"definition":"{asyncapi: \"2.0\", \"info\": { \"title: ... }}\n","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}]}'
{
"definition": "{asyncapi: \"2.0\", \"info\": { \"title: ... }}\n",
"references": [
{
"location": "https://example.com/api/models/pet.yml",
"content": "string"
}
]
}
{
"id": "3ef8f52f-9056-4113-840e-2f7183b90e06",
"expires_at": "2010-04-14 17:05:00 +0100",
"public_url": "https://bump.sh/preview/3ef8f52f-9056-4113-840e-2f7183b90e06"
}
{
"message": "Invalid definition file",
"errors": {
"raw_definition": [
"The property '#/paths//docs/{:id}/validations/post' contains additional properties [\"yolo\"] outside of the schema when none are allowed"
]
}
}
Update a preview with the given documentation file. The preview will stay active for 30 minutes after the last update.
UUID of an existing preview you wish to update.
The preview object
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.
Import external references used by definition
. It's usually resources not accessible by Bump servers, like local files or internal URLs.
Success
Unique id for the preview URL: https://bump.sh/preview/:id
.
Preview expiration date and time.
The public URL where the preview will be visible.
Definition is not valid.
curl \
-X PUT https://bump.sh/api/v1/previews/{preview_id} \
-H "Content-Type: application/json" \
-d '{"definition":"{asyncapi: \"2.0\", \"info\": { \"title: ... }}\n","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}]}'
{
"definition": "{asyncapi: \"2.0\", \"info\": { \"title: ... }}\n",
"references": [
{
"location": "https://example.com/api/models/pet.yml",
"content": "string"
}
]
}
{
"id": "3ef8f52f-9056-4113-840e-2f7183b90e06",
"expires_at": "2010-04-14 17:05:00 +0100",
"public_url": "https://bump.sh/preview/3ef8f52f-9056-4113-840e-2f7183b90e06"
}
{
"message": "Invalid definition file",
"errors": {
"raw_definition": [
"The property '#/paths//docs/{:id}/validations/post' contains additional properties [\"yolo\"] outside of the schema when none are allowed"
]
}
}
Deploy a new version for a given documentation, which will become the current version.
The version creation request object
UUID or slug of the documentation.
UUID or slug of the hub if the documentation is part of a hub.
Name of the documentation to create. Used only if auto_create_documentation
is set.
Create the documentation if it does not exist yet. Must be used with a hub
and a documentation
.
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.
Import external references used by definition
. It's usually resources not accessible by Bump servers, like local files or internal URLs.
Select a branch for this new version (branch will be created if it doesn't exist).
Defaults to the main branch.
UUID of a previously deployed version
Whether you want the new version to be unpublished or not. By default a new version will be published to your documentation.
curl \
-X POST https://bump.sh/api/v1/versions \
-H "Authorization: Token $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"documentation":"0776d85d-e097-47c1-8c60-cb1190d11945","hub":"my_hub_slug","documentation_name":"string","auto_create_documentation":false,"definition":"{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}],"branch_name":"string","previous_version_id":"3ef8f52f-9056-4113-840e-2f7183b90e06","unpublished":false}'
{
"documentation": "0776d85d-e097-47c1-8c60-cb1190d11945",
"hub": "my_hub_slug",
"documentation_name": "string",
"auto_create_documentation": false,
"definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n",
"references": [
{
"location": "https://example.com/api/models/pet.yml",
"content": "string"
}
],
"branch_name": "string",
"previous_version_id": "3ef8f52f-9056-4113-840e-2f7183b90e06",
"unpublished": false
}
{
"id": "2361df99-3467-4c80-a0cc-45c9fe565812",
"doc_id": "3ef8f52f-9056-4113-840e-2f7183b90e06",
"doc_public_url": "https://bump.sh/doc/my-own-documentation"
}
{
"message": "Invalid definition file",
"errors": {
"raw_definition": [
"The property '#/paths//docs/{:id}/validations/post' contains additional properties [\"yolo\"] outside of the schema when none are allowed"
]
}
}
Fetch a full documentation version including diff summary.
UUID of an existing version from which to fetch a documentation change
Success
Unique id of your version.
Unique id of your documentation.
The public URL of your documentation.
Details of each change as a list of diff items
The comparaison diff summary in markdown format
The comparaison diff summary
The public URL of your diff
Identifies if the diff includes breaking changes
Documentation version is still being processed. Please try again later
Version not found
curl \
-X GET https://bump.sh/api/v1/versions/{version_id} \
-H "Authorization: Token $ACCESS_TOKEN"
{
"id": "2361df99-3467-4c80-a0cc-45c9fe565812",
"doc_id": "3ef8f52f-9056-4113-840e-2f7183b90e06",
"doc_public_url": "https://bump.sh/doc/my-own-documentation",
"diff_details": [
{
"id": "post-versions",
"name": "POST /versions",
"status": "added",
"type": "endpoint",
"breaking": false,
"children": []
}
],
"diff_markdown": "## Modified (1)\n\n* `POST /user`\n * Path parameters added: `id`, `email`\n * Query parameters added: `period`, `limit`\n",
"diff_summary": "Updated: POST /versions\n Response modified: 201\n Body attribute added: doc_id\n",
"diff_public_url": "https://bump.sh/doc/my-own-documentation/change/2361df99-3467-4c80-a0cc-45c9fe565812",
"diff_breaking": false
}
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.
The version validation request object
UUID or slug of the documentation.
UUID or slug of the hub if the documentation is part of a hub.
Name of the documentation to create. Used only if auto_create_documentation
is set.
Create the documentation if it does not exist yet. Must be used with a hub
and a documentation
.
Required if definition
is not present.
Target definition URL. It should be accessible through HTTP by Bump servers..
Required 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.
Import external references used by definition
. It's usually resources not accessible by Bump servers, like local files or internal URLs.
Success
Specification of the given definition as a path: speficiation_name/specification_version/format
.
Values are openapi/v2/yaml
, openapi/v2/json
, openapi/v3/yaml
, openapi/v3/json
, asyncapi/v2/yaml
, or asyncapi/v2/json
.
Definition is not valid.
curl \
-X POST https://bump.sh/api/v1/validations \
-H "Authorization: Token $ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"documentation":"0776d85d-e097-47c1-8c60-cb1190d11945","hub":"my_hub_slug","documentation_name":"string","auto_create_documentation":false,"url":"https://example.com","definition":"{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}]}'
{
"documentation": "0776d85d-e097-47c1-8c60-cb1190d11945",
"hub": "my_hub_slug",
"documentation_name": "string",
"auto_create_documentation": false,
"url": "https://example.com",
"definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n",
"references": [
{
"location": "https://example.com/api/models/pet.yml",
"content": "string"
}
]
}
{
"specification": "openapi/v3/json"
}
{
"message": "Invalid definition file",
"errors": {
"raw_definition": [
"The property '#/paths//docs/{:id}/validations/post' contains additional properties [\"yolo\"] outside of the schema when none are allowed"
]
}
}
Fetch information of an existing Hub including the list of APIs it contains. The response follows the APIs.json specification
UUID or slug of a Hub which can be CI deployment settings page of your hub
Hub successfully retrieved
The name of the Hub
The description of the Hub
The public URL of the hub
Creation date of this Hub
Last udpate date of this Hub
The list of APIs belonging to this Hub
UUID of this API
Name of this API
Description of this API from the latest definition
Slug of this API
public documentation URL
Version of this API taken from the latest definition
Extra properties attached to this API
Creation date of this API
Last udpate date of this API
Hub not found
curl \
-X GET https://bump.sh/api/v1/hubs/{hub_id_or_slug} \
-H "Authorization: Token $ACCESS_TOKEN"
{
"name": "My train company hub",
"description": "# Welcome to my train company\n\nThis hub contains all APIs belonging to [my train company](https://demo.bump.sh/).\nFeel free to visit the documentations or changes of our APIs lifecycle.\n",
"url": "https://demo.bump.sh/",
"created": "2022-01-07",
"modified": "2022-04-07",
"apis": [
{
"id": "3ef8f52f-9056-4113-840e-2f7183b90e06",
"name": "Bump",
"description": "This is the official Bump API documentation. Obviously created with Bump.",
"slug": "bump",
"url": "https://developers.bump.sh/",
"version": "1.0",
"properties": [
{
"type": "x-access-level",
"data": "string"
}
],
"created": "2022-01-07",
"modified": "2022-04-07"
}
]
}
Payload sent when your documentation receives a deployment with a structure change.
The hash signature of the payload. Bump uses a HMAC hex digest (SHA256) to compute the signature of the body payload with the webhook secret. More info in help.
Information about last documentation structure change of your API history
UUID of this API
Name of this API
Description of this API from the latest definition
Slug of this API
public documentation URL
Version of this API taken from the latest definition
Extra properties attached to this API
Creation date of this API
Last udpate date of this API
Unique id of your diff
The title of the last parsed definition
The public URL of your diff
Identifies if the diff includes breaking changes
Details of each change as a list of diff items
URL of previous version specification, in JSON format
URL of current version specification, in JSON format
# Headers
X_BUMP_SIGNATURE_256: a0b1c1d2e3f5a8b13c21d34e55f89a144b233c377d610e987f1597a2584b4181
# Payload
{
"api": {
"id": "42",
"name": "Bump",
"description": "The official Bump API documentation",
"slug": "bump",
"url": "https://developers.bump.sh/",
"version": "1.0",
"created": "2019-05-05",
"modified": "2022-04-07"
},
"diff": {
"id": "ef41eb26-5e7f-47b9-9854-fa170d46bbd2",
"title": "Bump Api",
"public_url": "https://developers.bump.sh/changes/ef41eb26-5e7f-47b9-9854-fa170d46bbd2",
"breaking": false,
"details": [
{
"id": "post-DocStructureChange",
"name": "POST DocStructureChange",
"status": "added",
"type": "webhook",
"breaking": false,
"children": []
}
],
"previous_version_url": "https://developers.bump.sh/changes/ef41eb26-5e7f-47b9-9854-fa170d46bbd2/previous.json",
"current_version_url": "https://developers.bump.sh/changes/ef41eb26-5e7f-47b9-9854-fa170d46bbd2/current.json"
}
}