Bump Api

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 28, 2021.

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.

Ping

Check the API status

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

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

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.x, 3.x or AsyncAPI 2.x 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.

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

Definition
POST https://bump.sh/api/v1/previews
cURL example
curl \ -X POST https://bump.sh/api/v1/previews \ -H "Content-Type: application/json" \ -d '{"definition":"{asyncapi: \"2.0\", \"info\": { \"title: ... }}\n","specification":"openapi/v2/yaml","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}]}'
Request payload example
{ "definition": "{asyncapi: \"2.0\", \"info\": { \"title: ... }}\n", "specification": "openapi/v2/yaml", "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" ] } }

Validations

Validate a documentation definition

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

  • auto_create_documentation boolean

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

  • documentation_name string

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

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

  • specification string

    Specification for the 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, and asyncapi/v2/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

    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/validations
cURL example
curl \ -X POST https://bump.sh/api/v1/validations \ -H "Content-Type: application/json" \ -d '{"documentation":"0776d85d-e097-47c1-8c60-cb1190d11945","hub":"my_hub_slug","auto_create_documentation":true,"documentation_name":"string","definition":"{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n","specification":"openapi/v3/json","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}]}'
Request payload example
{ "documentation": "0776d85d-e097-47c1-8c60-cb1190d11945", "hub": "my_hub_slug", "auto_create_documentation": true, "documentation_name": "string", "definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n", "specification": "openapi/v3/json", "references": [ { "location": "https://example.com/api/models/pet.yml", "content": "string" } ] }
Response example (200)
No content
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

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

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

  • auto_create_documentation boolean

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

  • documentation_name string

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

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

  • specification string

    Specification for the 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, and asyncapi/v2/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

    Documentation version successfully created

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

Definition
POST https://bump.sh/api/v1/versions
cURL example
curl \ -X POST https://bump.sh/api/v1/versions \ -H "Content-Type: application/json" \ -d '{"documentation":"0776d85d-e097-47c1-8c60-cb1190d11945","hub":"my_hub_slug","auto_create_documentation":true,"documentation_name":"string","definition":"{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n","specification":"openapi/v3/json","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}]}'
Request payload example
{ "documentation": "0776d85d-e097-47c1-8c60-cb1190d11945", "hub": "my_hub_slug", "auto_create_documentation": true, "documentation_name": "string", "definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n", "specification": "openapi/v3/json", "references": [ { "location": "https://example.com/api/models/pet.yml", "content": "string" } ] }
Response example (201)
{ "doc_id": "3ef8f52f-9056-4113-840e-2f7183b90e06", "doc_public_url": "https://bump.sh/doc/my-own-documentation" }
Response example (204)
No content
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" ] } }