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. This documentation has been updated on Mar 1, 2019.

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.

Definition:

POST https://bump.sh/api/v1/docs/{:id}/versions

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.

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.

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

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.

Definition:

POST https://bump.sh/api/v1/docs/{:id}/validations

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.

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.

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

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.

Definition:

POST https://bump.sh/api/v1/previews

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.

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.

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

Example response (200):

{
  "id": "3ef8f52f-9056-4113-840e-2f7183b90e06",
  "expires_at": "2010-04-14T16:05:00+00:00"
}

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