Bump Api

This is the official Bump API documentation. Obviously created with Bump. Note that this is an experimental API on which everything could change.

This is the documentation for version 1.0 of the API. Last update on Feb 11, 2020.

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

Authentication

Api token authentication

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

Example: curl https://bump.sh/api/v1/docs/1/versions -u DOC_TOKEN:

Note that adding a colon after your token prevents cURL from asking for a password.

Docs

Create a new version

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

URL parameters
  • id Required / string

    Documentation's id

Body
  • definition Required / string

    Serialized definition of the version. This should be an OpenApi 2.0 (Swagger) file serialized as a string, in YAML or JSON.

  • specification string

    Specification for the definition, as a path: speficiation_name/specification_version/format. Example: openapi/v2/yaml.

    Values are openapi/v2/yaml, openapi/v2/json, openapi/v3/yaml, and openapi/v3/json.

  • validation string

    Validation strategy:
    - basic: basic validation (default)
    - strict: validate the file against its specification

Responses
  • • 200

    Success

  • • 422 object

    Definition is not valid.

    • message string

      Human readable error message.

    • errors object

      Hash of invalid attributes with their error messages.

Definition
POST https://bump.sh/api/v1/docs/{:id}/versions
Example request
$ curl \ -X POST https://bump.sh/api/v1/docs/{:id}/versions \ -H "Content-Type: application/json" \ -d '{"definition":"{swagger: \"2.0\", \"info\": { \"title: ... }}\n","specification":"openapi/v2/yam...}'
Example response (200)
No content
Example response (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" ] } }

Validate a documentation definition

Validate a definition against the OpenApi v2.0 schema 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 updated on Bump.

URL parameters
  • id Required / string

    Documentation's id

Body
  • definition Required / string

    Serialized definition of the version. This should be an OpenApi 2.0 (Swagger) file serialized as a string, in YAML or JSON.

  • specification string

    Specification for the definition, as a path: speficiation_name/specification_version/format. Example: openapi/v2/yaml.

    Values are openapi/v2/yaml, openapi/v2/json, openapi/v3/yaml, and openapi/v3/json.

  • validation string

    Validation strategy:
    - basic: basic validation (default)
    - strict: validate the file against its specification

Responses
  • • 200

    Success

  • • 422 object

    Definition is not valid.

    • message string

      Human readable error message.

    • errors object

      Hash of invalid attributes with their error messages.

Definition
POST https://bump.sh/api/v1/docs/{:id}/validations
Example request
$ curl \ -X POST https://bump.sh/api/v1/docs/{:id}/validations \ -H "Content-Type: application/json" \ -d '{"definition":"{swagger: \"2.0\", \"info\": { \"title: ... }}\n","specification":"openapi/v2/yam...}'
Example response (200)
No content
Example response (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" ] } }

Previews

Create a preview

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

Body
  • definition Required / string

    Serialized definition of the version. This should be an OpenApi 2.0 (Swagger) file serialized as a string, in YAML or JSON.

  • specification string

    Specification for the definition, as a path: speficiation_name/specification_version/format. Example: openapi/v2/yaml.

    Values are openapi/v2/yaml, openapi/v2/json, openapi/v3/yaml, and openapi/v3/json.

  • validation string

    Validation strategy:
    - basic: basic validation (default)
    - strict: validate the file against its specification

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.

  • • 422 object

    Definition is not valid.

    • message string

      Human readable error message.

    • errors object

      Hash of invalid attributes with their error messages.

Definition
POST https://bump.sh/api/v1/previews
Example request
$ curl \ -X POST https://bump.sh/api/v1/previews \ -H "Content-Type: application/json" \ -d '{"definition":"{swagger: \"2.0\", \"info\": { \"title: ... }}\n","specification":"openapi/v2/yam...}'
Example response (200)
{ "id": "3ef8f52f-9056-4113-840e-2f7183b90e06", "expires_at": "2010-04-14 17:05:00 +0100" }
Example response (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" ] } }