Create a new version

POST /versions
Authorization token Basic token

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

Body

The version creation request object

  • documentation string Required

    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.

    Default value is false.

  • definition string Required

    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.

    Hide references attributes Show references attributes array[object]
    • 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.

  • branch_name string

    Select a branch for this new version (branch will be created if it doesn't exist).

    Defaults to the main branch.

  • 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

    Documentation version successfully created

    Hide response attributes Show response attributes object
    • 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

    Definition is not valid.

    Hide response attributes Show response attributes object
    • 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 \
 -H "Authorization: Token $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"definition":"{\"openapi\": \"3.1.0\", \"info\": { \"title\": … }}","references":[{"location":"https://example.com/api/models/pet.yml","content":"string"}],"branch_name":"dev","documentation":"my_api_slug"}'
Request examples 
{
  "definition": "{\"openapi\": \"3.1.0\", \"info\": { \"title\": … }}",
  "references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ],
  "branch_name": "dev",
  "documentation": "my_api_slug"
}
{
  "definition": "{\"openapi\": \"3.1.0\", \"info\": { \"title\": … }}",
  "references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ],
  "documentation": "my_new_api_slug",
  "documentation_name": "My new API documentation",
  "auto_create_documentation": true
}
{
  "definition": "{\"openapi\": \"3.1.0\", \"info\": { \"title\": … }}",
  "references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ],
  "documentation": "my_new_api_slug",
  "documentation_name": "My new API documentation",
  "auto_create_documentation": true,
  "hub": "my_hub_slug"
}
Request examples 
{
  "documentation": "0776d85d-e097-47c1-8c60-cb1190d11945",
  "hub": "my_hub_slug",
  "documentation_name": "string",
  "auto_create_documentation": false,
  "definition": "{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n",
  "references": [
    {
      "location": "https://example.com/api/models/pet.yml",
      "content": "string"
    }
  ],
  "branch_name": "string",
  "previous_version_id": "3ef8f52f-9056-4113-840e-2f7183b90e06",
  "unpublished": false
}
Response examples (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 examples (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 examples (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"
    ]
  }
}
Response examples (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"
    ]
  }
}