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 Oct 1, 2021.

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

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/versions/1 -u DOC_TOKEN:

Adding a colon after your token prevents cURL from asking for a password.


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

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

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.

  • 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

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

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 string

    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.

  • 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

    Success

  • 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 \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"documentation":"0776d85d-e097-47c1-8c60-cb1190d11945","hub":"my_hub_slug","documentation_name":"string","auto_create_documentation":true,"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": true,
  "definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n",
  "references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ]
}
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

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

Body
  • documentation string

    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.

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

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

    • 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 \
 --user "username:password" \
 -H "Content-Type: application/json" \
 -d '{"documentation":"0776d85d-e097-47c1-8c60-cb1190d11945","hub":"my_hub_slug","documentation_name":"string","auto_create_documentation":true,"definition":"{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n","references":[{"location":"https://example.com/api/models/pet.yml","content":"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": true,
  "definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": ... }}\n",
  "references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "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

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.

    • The public URL of your documentation.

    • diff_summary string

      The comparaison diff summary

    • 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} \
 --user "username:password"
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_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
}