Bump Api

1.0

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.

Base URL

https://bump.sh/api/v1

Diffs

Create a diff

POST /diffs

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.

Body

The diff creation request object

url string(uri)

Required if definition is not present.
Current definition URL. It should be accessible through HTTP by Bump servers..
previous_url string(uri)

Required if definition is not present.
Previous definition URL. It should be accessible through HTTP by Bump servers..
previous_definition string

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.
previous_references array[object]

Import external references used by previous_definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.
- location string
  
  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.
- content string
  
  Content of the external reference, as a string.
definition string

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.
references array[object]

Import external references used by definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.
- location string
  
  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.
- content string
  
  Content of the external reference, as a string.
expires_at string(date-time)

Public change expiration date and time. After this date, this documentation change will be destroyed.

Responses

• 201 object

Diff successfully created
- id string
  
  Unique id of your diff
• 422 object

Definition is not valid.
- message string
  
  Human readable error message.
- errors object
  
  Hash of invalid attributes with their error messages.

POST /diffs

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"}'

Request example

{
  "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"
}

Response example (201)

{
  "id": "d6f00a51-a175-4a44-a0c7-df62a48548ca"
}

Response example (422)

{
  "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 detailed information from an existing diff

GET /diffs/{id}

Fetch the result of a previously created diff with the POST /diffs API endpoint.

Path parameters

id Required / string

UUID of an existing diff from which to fetch diff details

Query parameters

formats array[string]

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.

Responses

• 200 object

Diff successfully retrieved
- id string
  
  Unique id of your diff
- title string
  
  The title of the last parsed definition
- public_url string
  
  The public URL of your diff
- breaking boolean
  
  Identifies if the diff includes breaking changes
- details array[object]
  
  Details of each change as a list of diff items
  id string
  
  The identifier of the diff change
  
  name string
  
  The human name of diff change
  
  status string
  
  Values are added, modified, or removed.
  
  type string
  
  The object type of the diff change
  
  breaking boolean
  
  Identifies if the item is a breaking change
  
  children array
  
  A list of children item changes
- previous_version_url string
  
  URL of previous version specification, in JSON format
- current_version_url string
  
  URL of current version specification, in JSON format
- markdown string
  
  The comparaison diff summary in markdown format
- html string
  
  The comparaison diff summary in HTML format
- text string
  
  The comparaison diff summary in plain text format
• 202

Diff is still being processed. Please try again later
• 404

Diff not found

GET /diffs/{id}

curl \
 -X GET https://bump.sh/api/v1/diffs/{id}

Response examples (200)

{
  "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": []
    }
  ]
}

Ping

Check the API status

GET /ping

Responds a pong if the API is up and running.

Responses

• 200 object

Success
- pong string
  
  Sentence about ping and pong
• default

API is currently down

GET /ping

curl \
 -X GET https://bump.sh/api/v1/ping

Response example (200)

{
  "pong": "And that's how ping-pong ball is bumped"
}

Previews

Create a preview

POST /previews

Create a preview for a given documentation file. The preview will have a unique temporary URL, and will be active for 30 minutes.

Body

The preview object

definition Required / string

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.
references array[object]

Import external references used by definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.
- location string
  
  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.
- content string
  
  Content of the external reference, as a string.

Responses

• 201 object

Success
- id string
  
  Unique id for the preview URL: https://bump.sh/preview/:id.
- expires_at string(date-time)
  
  Preview expiration date and time.
- public_url string
  
  The public URL where the preview will be visible.
• 422 object

Definition is not valid.
- message string
  
  Human readable error message.
- errors object
  
  Hash of invalid attributes with their error messages.

POST /previews

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"}]}'

Request example

{
  "definition": "{asyncapi: \"2.0\", \"info\": { \"title: ... }}\n",
  "references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ]
}

Response example (201)

{
  "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"
}

Response example (422)

{
  "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 an existing preview

PUT /previews/{preview_id}

Update a preview with the given documentation file. The preview will stay active for 30 minutes after the last update.

Path parameters

preview_id Required / string

UUID of an existing preview you wish to update.

Body

The preview object

definition Required / string

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.
references array[object]

Import external references used by definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.
- location string
  
  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.
- content string
  
  Content of the external reference, as a string.

Responses

• 200 object

Success
- id string
  
  Unique id for the preview URL: https://bump.sh/preview/:id.
- expires_at string(date-time)
  
  Preview expiration date and time.
- public_url string
  
  The public URL where the preview will be visible.
• 422 object

Definition is not valid.
- message string
  
  Human readable error message.
- errors object
  
  Hash of invalid attributes with their error messages.

PUT /previews/{preview_id}

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"}]}'

Request example

{
  "definition": "{asyncapi: \"2.0\", \"info\": { \"title: ... }}\n",
  "references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ]
}

Response example (200)

{
  "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"
}

Response example (422)

{
  "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"
    ]
  }
}

Versions

Create a new version

POST /versions

Authorization token Basic token

Deploy a new version for a given documentation, which will become the current version.

Body

The version creation request object

documentation Required / string

UUID or slug of the documentation.
hub string

UUID or slug of the hub if the documentation is part of a hub.
documentation_name string

Name of the documentation to create. Used only if auto_create_documentation is set.
auto_create_documentation boolean

Create the documentation if it does not exist yet. Must be used with a hub and a documentation.
definition Required / string

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.
references array[object]

Import external references used by definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.
- location string
  
  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.
- content string
  
  Content of the external reference, as a string.
branch_name string

Select a branch for this new version (branch will be created if it doesn't exist).

Defaults to the main branch.
previous_version_id string

UUID of a previously deployed version
unpublished boolean

Whether you want the new version to be unpublished or not. By default a new version will be published to your documentation.

Responses

• 201 object

Documentation version successfully created
- id string
  
  Unique id of your version.
- doc_id string
  
  Unique id of your documentation.
- doc_public_url string
  
  The public URL of your documentation.
• 204

Documentation is unchanged
• 422 object

Definition is not valid.
- message string
  
  Human readable error message.
- errors object
  
  Hash of invalid attributes with their error messages.

POST /versions

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}'

Request example

{
  "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
}

Response example (201)

{
  "id": "2361df99-3467-4c80-a0cc-45c9fe565812",
  "doc_id": "3ef8f52f-9056-4113-840e-2f7183b90e06",
  "doc_public_url": "https://bump.sh/doc/my-own-documentation"
}

Response example (422)

{
  "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

GET /versions/{version_id}

Authorization token Basic token

Fetch a full documentation version including diff summary.

Path parameters

version_id Required / string

UUID of an existing version from which to fetch a documentation change

Responses

• 200 object

Success
- id string
  
  Unique id of your version.
- doc_id string
  
  Unique id of your documentation.
- doc_public_url string
  
  The public URL of your documentation.
- diff_details array[object]
  
  Details of each change as a list of diff items
  id string
  
  The identifier of the diff change
  
  name string
  
  The human name of diff change
  
  status string
  
  Values are added, modified, or removed.
  
  type string
  
  The object type of the diff change
  
  breaking boolean
  
  Identifies if the item is a breaking change
  
  children array
  
  A list of children item changes
- diff_markdown string
  
  The comparaison diff summary in markdown format
- diff_summary string
  
  The comparaison diff summary
- diff_public_url string
  
  The public URL of your diff
- diff_breaking boolean
  
  Identifies if the diff includes breaking changes
• 202

Documentation version is still being processed. Please try again later
• 404

Version not found

GET /versions/{version_id}

curl \
 -X GET https://bump.sh/api/v1/versions/{version_id} \
 -H "Authorization: Token $ACCESS_TOKEN"

Response example (200)

{
  "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
}

Validations

Validate a documentation definition

POST /validations

Authorization token Basic token

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.

Body

The version validation request object

documentation Required / string

UUID or slug of the documentation.
hub string

UUID or slug of the hub if the documentation is part of a hub.
documentation_name string

Name of the documentation to create. Used only if auto_create_documentation is set.
auto_create_documentation boolean

Create the documentation if it does not exist yet. Must be used with a hub and a documentation.
url string(uri)

Required if definition is not present.
Target definition URL. It should be accessible through HTTP by Bump servers..
definition string

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.
references array[object]

Import external references used by definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.
- location string
  
  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.
- content string
  
  Content of the external reference, as a string.

Responses

• 200 object

Success
- specification string
  
  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.
• 422 object

Definition is not valid.
- message string
  
  Human readable error message.
- errors object
  
  Hash of invalid attributes with their error messages.

POST /validations

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"}]}'

Request example

{
  "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"
    }
  ]
}

Response example (200)

{
  "specification": "openapi/v3/json"
}

Response example (422)

{
  "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"
    ]
  }
}

Hubs

Fetch information of an existing Hub

GET /hubs/{hub_id_or_slug}

Authorization token Basic token

Fetch information of an existing Hub including the list of APIs it contains. The response follows the APIs.json specification

Path parameters

hub_id_or_slug Required / string

UUID or slug of a Hub which can be CI deployment settings page of your hub

Responses

• 200 object

Hub successfully retrieved
- name string
  
  The name of the Hub
- description string
  
  The description of the Hub
- url string
  
  The public URL of the hub
- created date
  
  Creation date of this Hub
- modified date
  
  Last udpate date of this Hub
- apis array[object]
  
  The list of APIs belonging to this Hub
  id string
  
  UUID of this API
  
  name string
  
  Name of this API
  
  description string
  
  Description of this API from the latest definition
  
  slug string
  
  Slug of this API
  
  url string
  
  public documentation URL
  
  version string
  
  Version of this API taken from the latest definition
  
  properties array[object]
  
  Extra properties attached to this API
  
  type string
  
  Type of the extra property
  
  Values are x-access-level or x-definition-type.
  
  data string
  
  Content of the extra property
  
  created date
  
  Creation date of this API
  
  modified date
  
  Last udpate date of this API
• 404

Hub not found

GET /hubs/{hub_id_or_slug}

curl \
 -X GET https://bump.sh/api/v1/hubs/{hub_id_or_slug} \
 -H "Authorization: Token $ACCESS_TOKEN"

Response example (200)

{
  "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"
    }
  ]
}

X_BUMP_SIGNATURE_256 Required / string

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.

Body

Information about last documentation structure change of your API history

api Required / object
- id string
  
  UUID of this API
- name string
  
  Name of this API
- description string
  
  Description of this API from the latest definition
- slug string
  
  Slug of this API
- url string
  
  public documentation URL
- version string
  
  Version of this API taken from the latest definition
- properties array[object]
  
  Extra properties attached to this API
  type string
  
  Type of the extra property
  
  Values are x-access-level or x-definition-type.
  
  data string
  
  Content of the extra property
- created date
  
  Creation date of this API
- modified date
  
  Last udpate date of this API
diff Required / object
- id string
  
  Unique id of your diff
- title string
  
  The title of the last parsed definition
- public_url string
  
  The public URL of your diff
- breaking boolean
  
  Identifies if the diff includes breaking changes
- details array[object]
  
  Details of each change as a list of diff items
  id string
  
  The identifier of the diff change
  
  name string
  
  The human name of diff change
  
  status string
  
  Values are added, modified, or removed.
  
  type string
  
  The object type of the diff change
  
  breaking boolean
  
  Identifies if the item is a breaking change
  
  children array
  
  A list of children item changes
- previous_version_url string
  
  URL of previous version specification, in JSON format
- current_version_url string
  
  URL of current version specification, in JSON format

POST DocStructureChange

Request example

# 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"
  }
}