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

Base URL

https://bump.sh/api/v1

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

GET /ping

curl \
 -X GET https://bump.sh/api/v1/ping

Response example (200)

{
  "pong": "And that's how ping-pong ball is bumped"
}

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.
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 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.
documentation_name string

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

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

Versions

Create a new version

Basic token

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.
documentation_name string

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

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

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

Basic token

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.
- doc_public_url string
  
  The public URL of your documentation.
- diff_summary string
  
  The comparaison diff summary
- diff_public_url string
  
  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
}

Bump Api

Authentication

Api token authentication

Ping

Check the API status

Responses

Previews

Create a preview

Body

Responses

Update an existing preview

Path parameters

Body

Responses

Validations

Validate a documentation definition

Body

Responses

Versions

Create a new version

Body

Responses

Fetch a full documentation version including diff summary

Path parameters

Responses