Bump Api
1.0

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 or preview your API(s) documentation, create stand-alone documentation diffs or validate a documentation definition (currently in OpenAPI or AsyncAPI).
Our webhook also lets you get notifications every time a change is introduced in your API.

This is the documentation for version 1.0 of the API. Last update on Dec 6, 2022.

Base URL
https://bump.sh/api/v1

Authentication

Http token authentication

This is the preferred authentication method for restricted access API endpoints

Use the token from your documentation settings in the HTTP token authorization header.

Basic authentication

(Deprecated) Use the token from your documentation settings as the username of the basic auth, with no password.

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

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.

  • 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.

  • 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 string Required

    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

    • 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

      • A list of children item changes

    • URL of previous version specification, in JSON format

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

Check the API status

GET /ping

Responds a pong if the API is up and running.

Responses

GET /ping
curl \
 -X GET https://bump.sh/api/v1/ping
Response example (200)
{
  "pong": "And that's how ping-pong ball is bumped"
}

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 string Required

    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.

    • 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 string Required

    UUID of an existing preview you wish to update.

Body

The preview object

  • definition string Required

    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.

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

Create a new version

POST /versions

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

Body

The version creation request object

  • documentation string Required

    UUID or slug of the documentation.

  • hub string

    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.

    Default value is false.

  • definition string Required

    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.

  • 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.

Responses

  • 201 object

    Documentation version successfully created

    • id string

      Unique id of your version.

    • doc_id string

      Unique id of your documentation.

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

Fetch a full documentation version including diff summary.

Path parameters

  • version_id string Required

    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.

    • 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

      • A list of children item changes

    • The comparaison diff summary in markdown format

    • The comparaison diff summary

    • The public URL of your diff

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

Validate a documentation definition

POST /validations

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 string Required

    UUID or slug of the documentation.

  • hub string

    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.

    Default value is false.

  • url string(uri)

    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.

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

Fetch information of an existing Hub

GET /hubs/{hub_id_or_slug}

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 string Required

    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

    • The description of the Hub

    • url string

      The public URL of the hub

    • Creation date of this Hub

    • 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 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

      • Creation date of this API

      • 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 documentation 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"
    }
  ]
}

Structure change

POST /DocStructureChange

Payload sent when your documentation receives a deployment with a structure change.

Headers

  • X_BUMP_SIGNATURE_256 string Required

    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 object Required
    • id string

      UUID of this API

    • name string

      Name of this API

    • 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

    • Creation date of this API

    • Last udpate date of this API

  • diff object Required
    • id string

      Unique id of your diff

    • title string

      The title of the last parsed definition

    • 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

      • A list of children item changes

    • URL of previous version specification, in JSON format

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