Bump API documentation

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 Feb 15, 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
Show response Hide response
- 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.
validation string
Validation strategy:
- basic: basic validation (default)
- strict: validate the file against its specification
references array[object]

Import external references used by definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.
Show child attributes Hide child attributes
- references.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.
- references.content string
  
  Content of the external reference, as a string.

Responses

• 200 object

Success
Show response Hide response
- 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.
Show response Hide response
- 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","validation":"string","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",
  "validation": "string",
  "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"
}

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_id string

UUID of the documentation. Required if documentation_slug is empty.
documentation_slug string

Slug of the documentation. Required if documentation_id is empty.
hub_id string

UUID of the hub if the documentation is part of a hub.
hub_slug string

Slug of the hub if the documentation is part of a hub.
auto_create_documentation boolean

Create the documentation if not existing yet. Must be used with a hub_id or hub_slug, and a documentation_slug.
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.
validation string
Validation strategy:
- basic: basic validation (default)
- strict: validate the file against its specification
references array[object]

Import external references used by definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.
Show child attributes Hide child attributes
- references.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.
- references.content string
  
  Content of the external reference, as a string.

Responses

• 200

Success
• 422 object

Definition is not valid.
Show response Hide response
- 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_id":"string","documentation_slug":"string","hub_id":"string","hub_slug":"string","auto_create_documentation":true,"definition":"{openapi: \"3.0\", \"info\": { \"title: ... }}\n","specification":"openapi/v2/yaml","validation":"string","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}]}'

Request payload example

{
  "documentation_id": "string",
  "documentation_slug": "string",
  "hub_id": "string",
  "hub_slug": "string",
  "auto_create_documentation": true,
  "definition": "{openapi: \"3.0\", \"info\": { \"title: ... }}\n",
  "specification": "openapi/v2/yaml",
  "validation": "string",
  "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_id string

UUID of the documentation. Required if documentation_slug is empty.
documentation_slug string

Slug of the documentation. Required if documentation_id is empty.
hub_id string

UUID of the hub if the documentation is part of a hub.
hub_slug string

Slug of the hub if the documentation is part of a hub.
auto_create_documentation boolean

Create the documentation if not existing yet. Must be used with a hub_id or hub_slug, and a documentation_slug.
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.
validation string
Validation strategy:
- basic: basic validation (default)
- strict: validate the file against its specification
references array[object]

Import external references used by definition. It's usually resources not accessible by Bump servers, like local files or internal URLs.
Show child attributes Hide child attributes
- references.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.
- references.content string
  
  Content of the external reference, as a string.

Responses

• 200

Success
• 422 object

Definition is not valid.
Show response Hide response
- 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_id":"string","documentation_slug":"string","hub_id":"string","hub_slug":"string","auto_create_documentation":true,"definition":"{openapi: \"3.0\", \"info\": { \"title: ... }}\n","specification":"openapi/v2/yaml","validation":"string","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}]}'

Request payload example

{
  "documentation_id": "string",
  "documentation_slug": "string",
  "hub_id": "string",
  "hub_slug": "string",
  "auto_create_documentation": true,
  "definition": "{openapi: \"3.0\", \"info\": { \"title: ... }}\n",
  "specification": "openapi/v2/yaml",
  "validation": "string",
  "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"
    ]
  }
}