{"openapi":"3.1.0","info":{"title":"Bump Api","description":"This is the official Bump.sh API documentation. Obviously created with Bump.sh.\n\nThe Bump.sh API is a REST API. It enables you to [create, update](#operation-post-versions) or [preview](#operation-post-previews) your API(s) documentation, [create stand-alone documentation diffs](#operation-post-diffs) or [validate a documentation definition](#operation-post-validations) (currently in OpenAPI or AsyncAPI).\nOur [webhook](#webhook-documentation-change) also lets you get notifications every time a change is introduced in your API.\n","version":"1.0"},"servers":[{"url":"https://bump.sh/api/v1"}],"x-topics":[{"title":"Authentication","content":{"$ref":"./authentication.md"},"example":{"$ref":"./authentication-example.md"}}],"tags":[{"name":"Diffs","description":"Diff summary of changes in the API"},{"name":"Versions","description":"Deploy your API contracts"},{"name":"Validations","description":"Check \u0026 validate your API contracts"},{"name":"Hubs","description":"Interact with your Hubs"},{"name":"Documentation change","description":"Check \u0026 validate your API contracts"}],"paths":{"/diffs":{"post":{"tags":["Diffs"],"summary":"Create a diff","description":"Create a diff between any two given API definitions.\nThe diff result will be available asynchronously and needs to be retrieved with the [`GET /diffs/:id` API endpoint](#operation-get-diffs-parameter).\n","security":[],"requestBody":{"$ref":"#/components/requestBodies/Diff"},"responses":{"201":{"description":"Diff successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"Unique id of your diff","example":"d6f00a51-a175-4a44-a0c7-df62a48548ca"}}}}}},"422":{"$ref":"#/components/responses/InvalidDefinition"}}}},"/diffs/{id}":{"get":{"tags":["Diffs"],"summary":"Fetch detailed information from an existing diff","description":"Fetch the result of a previously created diff with the [`POST /diffs` API endpoint](#operation-post-diffs).\n","security":[],"parameters":[{"in":"path","name":"id","schema":{"type":"string","description":"UUID of an existing diff"},"required":true,"description":"UUID of an existing diff from which to fetch diff details"},{"in":"query","name":"formats","description":"A list of formats to render in the response. Possible values are `text`, `markdown`, `html` or `json`. If not provided defaults to render both `text` and `markdown` formats.\n","schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Diff successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiffForApi"},"examples":{"default":{"$ref":"#/components/examples/DefaultDiff"},"html":{"$ref":"#/components/examples/HTMLDiff"},"json":{"$ref":"#/components/examples/JSONDiff"}}}}},"202":{"description":"Diff is still being processed. Please try again later"},"404":{"description":"Diff not found"}}}},"/hubs/{hub_id_or_slug}":{"get":{"tags":["Hubs"],"summary":"Fetch information of an existing Hub","description":"Fetch information of an existing Hub including the list of APIs it contains. The response follows the [APIs.json specification](http://apisjson.org/)\n","parameters":[{"in":"path","name":"hub_id_or_slug","schema":{"type":"string","description":"UUID or slug of a Hub"},"required":true,"description":"UUID or slug of a Hub which can be CI deployment settings page of your hub"}],"responses":{"200":{"description":"Hub successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hub"}}}},"404":{"description":"Hub not found"}}}},"/versions":{"post":{"tags":["Versions"],"summary":"Create a new version","description":"Deploy a new version for a given documentation, which will become the current version.\n","requestBody":{"$ref":"#/components/requestBodies/Version"},"responses":{"201":{"description":"Documentation version successfully created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Version"}}}},"204":{"description":"Documentation is unchanged"},"422":{"$ref":"#/components/responses/InvalidDefinition"}}}},"/validations":{"post":{"tags":["Validations"],"summary":"Validate a documentation definition","description":"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.\n","security":[{},{"Authorization token":[]},{"Basic token":[]}],"requestBody":{"$ref":"#/components/requestBodies/Validate"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Validation"}}}},"422":{"$ref":"#/components/responses/InvalidDefinition"}}}},"/previews":{"post":{"tags":["Previews"],"summary":"Create a preview","description":"Create a preview for a given documentation file. The preview will have a unique temporary URL, and will be active for 30 minutes.\n","security":[],"requestBody":{"$ref":"#/components/requestBodies/Preview"},"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Preview"}}}},"422":{"$ref":"#/components/responses/InvalidDefinition"}}}},"/previews/{preview_id}":{"put":{"tags":["Previews"],"summary":"Update an existing preview","description":"Update a preview with the given documentation file. The preview will stay active for 30 minutes after the last update.\n","security":[],"parameters":[{"in":"path","name":"preview_id","schema":{"type":"string"},"required":true,"description":"UUID of an existing preview you wish to update."}],"requestBody":{"$ref":"#/components/requestBodies/Preview"},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Preview"}}}},"422":{"$ref":"#/components/responses/InvalidDefinition"}}}},"/versions/{version_id}":{"get":{"tags":["Versions"],"summary":"Fetch a full documentation version including diff summary","description":"Fetch a full documentation version including diff summary.\n","parameters":[{"in":"path","name":"version_id","schema":{"type":"string","description":"UUID of an existing documentation version."},"required":true,"description":"UUID of an existing version from which to fetch a documentation change"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Version"},{"$ref":"#/components/schemas/WithDiff"}]}}}},"202":{"description":"Documentation version is still being processed. Please try again later"},"404":{"description":"Version not found"}}}},"/ping":{"get":{"tags":["Ping"],"summary":"Check the API status","description":"Responds a pong if the API is up and running.","security":[],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Pong"}}}},"default":{"description":"API is currently down"}}}}},"webhooks":{"DocStructureChange":{"post":{"tags":["Documentation change"],"operationId":"webhookDocStructureChange","summary":"Structure change","description":"Payload sent when your documentation receives a deployment with a structure change.","security":[],"parameters":[{"name":"X_BUMP_SIGNATURE_256","in":"header","description":"The hash signature of the payload. Bump uses a HMAC hex digest (SHA256) to compute the signature of the body payload with the webhook secret. More info in help.","example":"a0b1c1d2e3f5a8b13c21d34e55f89a144b233c377d610e987f1597a2584b4181","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"Information about last documentation structure change of your API history","content":{"application/json":{"examples":{"new-webhook":{"summary":"Webhook payload example","value":{"api":{"id":"42","name":"Bump","description":"The official Bump API documentation","slug":"bump","url":"https://developers.bump.sh/","version":"1.0","created":"2019-05-05","modified":"2022-04-07"},"diff":{"id":"ef41eb26-5e7f-47b9-9854-fa170d46bbd2","title":"Bump Api","public_url":"https://developers.bump.sh/changes/ef41eb26-5e7f-47b9-9854-fa170d46bbd2","breaking":false,"details":[{"id":"post-DocStructureChange","name":"POST DocStructureChange","status":"added","type":"webhook","breaking":false,"children":[]}],"previous_version_url":"https://developers.bump.sh/changes/ef41eb26-5e7f-47b9-9854-fa170d46bbd2/previous.json","current_version_url":"https://developers.bump.sh/changes/ef41eb26-5e7f-47b9-9854-fa170d46bbd2/current.json"}}}},"schema":{"type":"object","required":["api","diff"],"properties":{"api":{"description":"Details of the affected API","$ref":"#/components/schemas/Api"},"diff":{"description":"Details of the documentation change","$ref":"#/components/schemas/Diff"}}}}}}}}},"security":[{"Authorization token":[]},{"Basic token":[]}],"components":{"securitySchemes":{"Authorization token":{"type":"http","scheme":"token"},"Basic token":{"type":"http","scheme":"basic"}},"requestBodies":{"Diff":{"description":"The diff creation request object","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DiffRequest"}}}},"Preview":{"description":"The preview object","content":{"application/json":{"schema":{"required":["definition"],"properties":{"definition":{"type":"string","description":"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.\n","example":"{asyncapi: \"2.0\", \"info\": { \"title: … }}\n"},"references":{"type":"array","description":"Import external references used by `definition`. It's usually resources not accessible by Bump servers, like local files or internal URLs.","items":{"$ref":"#/components/schemas/Reference"}}}}}}},"Validate":{"description":"The version validation request object","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/DocumentationRequest"},{"$ref":"#/components/schemas/PreviewRequest"}]}}}},"Version":{"description":"The version creation request object","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/DocumentationRequest"},{"$ref":"#/components/schemas/VersionRequest"},{"type":"object","properties":{"previous_version_id":{"type":"string","description":"UUID of a previously deployed version","example":"3ef8f52f-9056-4113-840e-2f7183b90e06"},"unpublished":{"type":"boolean","description":"Whether you want the new version to be unpublished or not. By default a new version will be published to your documentation.","example":false}}}]},"examples":{"default":{"$ref":"#/components/examples/NewVersion/ExistingDocumentation"},"auto_create_standalone":{"$ref":"#/components/examples/NewVersion/CreatingStandaloneDocumentation"},"auto_create_in_hub":{"$ref":"#/components/examples/NewVersion/CreatingDocumentationInHub"}}}}}},"responses":{"InvalidDefinition":{"description":"Definition is not valid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Hub":{"type":"object","properties":{"name":{"type":"string","description":"The name of the Hub","example":"My train company hub"},"description":{"type":"string","description":"The description of the Hub","example":"# Welcome to my train company\n\nThis hub contains all APIs belonging to [my train company](https://demo.bump.sh/).\nFeel free to visit the documentation or changes of our APIs lifecycle.\n"},"url":{"type":"string","description":"The public URL of the hub","example":"https://demo.bump.sh/"},"created":{"type":"date","description":"Creation date of this Hub","example":"2022-01-07"},"modified":{"type":"date","description":"Last udpate date of this Hub","example":"2022-04-07"},"apis":{"type":"array","description":"The list of APIs belonging to this Hub","items":{"$ref":"#/components/schemas/Api"}}}},"Api":{"type":"object","properties":{"id":{"type":"string","description":"UUID of this API","example":"3ef8f52f-9056-4113-840e-2f7183b90e06"},"name":{"type":"string","description":"Name of this API","example":"Bump"},"description":{"type":"string","description":"Description of this API from the latest definition","example":"This is the official Bump API documentation. Obviously created with Bump."},"slug":{"type":"string","description":"Slug of this API","example":"bump"},"url":{"type":"string","description":"public documentation URL","example":"https://developers.bump.sh/"},"version":{"type":"string","description":"Version of this API taken from the latest definition","example":"1.0"},"properties":{"type":"array","description":"Extra properties attached to this API","items":{"type":"object","properties":{"type":{"type":"string","description":"Type of the extra property","enum":["x-access-level","x-definition-type"]},"data":{"type":"string","description":"Content of the extra property"}}}},"created":{"type":"date","description":"Creation date of this API","example":"2022-01-07"},"modified":{"type":"date","description":"Last udpate date of this API","example":"2022-04-07"}}},"Reference":{"type":"object","properties":{"location":{"type":"string","description":"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.","example":"https://example.com/api/models/pet.yml"},"content":{"type":"string","description":"Content of the external reference, as a string."}}},"Error":{"properties":{"message":{"type":"string","description":"Human readable error message.","example":"Invalid definition file"},"errors":{"type":"object","description":"Hash of invalid attributes with their error messages.","example":{"raw_definition":["The property '#/paths//docs/{:id}/validations/post' contains additional properties [\"yolo\"] outside of the schema when none are allowed"]}}}},"Pong":{"properties":{"pong":{"type":"string","description":"Sentence about ping and pong","example":"And that's how ping-pong ball is bumped"}}},"Preview":{"properties":{"id":{"type":"string","description":"Unique id for the preview URL: `https://bump.sh/preview/:id`.","example":"3ef8f52f-9056-4113-840e-2f7183b90e06"},"expires_at":{"type":"string","format":"date-time","description":"Preview expiration date and time.","example":"2010-04-14T17:05:00+01:00"},"public_url":{"type":"string","description":"The public URL where the preview will be visible.","example":"https://bump.sh/preview/3ef8f52f-9056-4113-840e-2f7183b90e06"}}},"Version":{"properties":{"id":{"type":"string","description":"Unique id of your version.","example":"2361df99-3467-4c80-a0cc-45c9fe565812"},"doc_id":{"type":"string","description":"Unique id of your documentation.","example":"3ef8f52f-9056-4113-840e-2f7183b90e06"},"doc_public_url":{"type":"string","description":"The public URL of your documentation.","example":"https://bump.sh/doc/my-own-documentation"}}},"WithDiff":{"properties":{"diff_details":{"type":"array","description":"Details of each change as a list of diff items","items":{"$ref":"#/components/schemas/DiffItem"}},"diff_markdown":{"type":"string","description":"The comparaison diff summary in markdown format","example":"## Modified (1)\n\n* `POST /user`\n  * Path parameters added: `id`, `email`\n  * Query parameters added: `period`, `limit`\n"},"diff_summary":{"type":"string","description":"The comparaison diff summary","example":"Updated: POST /versions\n  Response modified: 201\n    Body attribute added: doc_id\n"},"diff_public_url":{"type":"string","description":"The public URL of your diff","example":"https://bump.sh/doc/my-own-documentation/change/2361df99-3467-4c80-a0cc-45c9fe565812"},"diff_breaking":{"type":"boolean","description":"Identifies if the diff includes breaking changes","example":false}}},"Diff":{"type":"object","properties":{"id":{"type":"string","description":"Unique id of your diff","example":"2361df99-1234-4c80-a0cc-45c9fe565812"},"title":{"type":"string","description":"The title of the last parsed definition","example":"Bump Api"},"public_url":{"type":"string","description":"The public URL of your diff","example":"https://bump.sh/doc/my-own-documentation/change/2361df99-3467-4c80-a0cc-45c9fe565812"},"breaking":{"type":"boolean","description":"Identifies if the diff includes breaking changes","example":false},"details":{"type":"array","description":"Details of each change as a list of diff items","items":{"$ref":"#/components/schemas/DiffItem"}},"previous_version_url":{"type":"string","description":"URL of previous version specification, in JSON format","example":"https://developers.bump.sh/changes/750f15d8-6c41-47b9-8f80-e3ed812dbca9/previous.json"},"current_version_url":{"type":"string","description":"URL of current version specification, in JSON format","example":"https://developers.bump.sh/changes/750f15d8-6c41-47b9-8f80-e3ed812dbca9/current.json"}}},"DiffItem":{"properties":{"id":{"type":"string","description":"The identifier of the diff change","example":"post-versions"},"name":{"type":"string","description":"The human name of diff change","example":"POST /versions"},"status":{"type":"string","enum":["added","modified","removed"]},"type":{"type":"string","description":"The object type of the diff change","example":"endpoint"},"breaking":{"type":"boolean","description":"Identifies if the item is a breaking change","example":false},"children":{"type":"array","description":"A list of children item changes","items":{"$ref":"#/components/schemas/DiffItem"}}}},"DiffForApi":{"allOf":[{"$ref":"#/components/schemas/Diff"},{"type":"object","properties":{"markdown":{"type":"string","description":"The comparaison diff summary in markdown format","example":"## Modified (1)\n\n* `POST /user`\n  * Path parameters added: `id`, `email`\n  * Query parameters added: `period`, `limit`\n"},"html":{"type":"string","description":"The comparaison diff summary in HTML format","example":"\u003cul class=\"changelog-event__diff expandable\" data-expander-target=\"content\"\u003e\n    \u003cli class=\"changelog-event__diff-operation added\"\u003e\n         Added: \u003ca href=\"http://localhost:3000/diff/c1e36203-5b04-4adc-b8c5-8ac626ce8592#operation-get-diffs-parameter\"\u003e\u003ccode class=\"code-inline root\"\u003eGET /diffs/{id}\u003c/code\u003e\u003c/a\u003e\n    \u003c/li\u003e\n\u003c/ul\u003e\n"},"text":{"type":"string","description":"The comparaison diff summary in plain text format","example":"Updated: POST /versions\n  Response modified: 201\n    Body attribute added: doc_id\n"}}}]},"DocumentationRequest":{"type":"object","required":["documentation"],"properties":{"documentation":{"type":"string","description":"UUID or slug of the documentation.","example":"0776d85d-e097-47c1-8c60-cb1190d11945"},"hub":{"type":"string","description":"UUID or slug of the hub if the documentation is part of a hub.","example":"my_hub_slug"},"documentation_name":{"type":"string","description":"Name of the documentation to create. Used only if `auto_create_documentation` is set."},"auto_create_documentation":{"type":"boolean","default":false,"description":"Create the documentation if it does not exist yet. Must be used with a `hub` and a `documentation`."}}},"Validation":{"properties":{"specification":{"type":"string","description":"Specification of the given definition as a path: `speficiation_name/specification_version/format`.","enum":["openapi/v2/yaml","openapi/v2/json","openapi/v3/yaml","openapi/v3/json","asyncapi/v2/yaml","asyncapi/v2/json"],"example":"openapi/v3/json"}}},"VersionRequest":{"type":"object","required":["definition"],"properties":{"definition":{"type":"string","description":"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.\n","example":"{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n"},"references":{"type":"array","description":"Import external references used by `definition`. It's usually resources not accessible by Bump servers, like local files or internal URLs.","items":{"$ref":"#/components/schemas/Reference"}},"branch_name":{"type":"string","description":"Select a branch for this new version (branch will be created if it doesn't exist).\n\n*Defaults to the main branch*.\n"}}},"PreviewRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"**Required** if [`definition`](#post-validations-definition) is not present.\nTarget definition URL. It should be accessible through HTTP by Bump servers.\n"},"definition":{"type":"string","description":"**Required** if [`url`](#post-validations-url) is not present.\nSerialized definition. This should be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file\nserialized as a string, in YAML or JSON.\n","example":"{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n"},"references":{"type":"array","description":"Import external references used by `definition`. It's usually resources not accessible by Bump servers, like local files or internal URLs.","items":{"$ref":"#/components/schemas/Reference"}}}},"DiffRequest":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"**Required** if `definition` is not present.\nCurrent definition URL. It should be accessible through HTTP by Bump servers.\n"},"previous_url":{"type":"string","format":"uri","description":"**Required** if `definition` is not present.\nPrevious definition URL. It should be accessible through HTTP by Bump servers.\n"},"previous_definition":{"type":"string","description":"**Required** if `url` is not present.\nSerialized definition of the previous version. This should be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file\nserialized as a string, in YAML or JSON.\n","example":"{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n"},"previous_references":{"type":"array","description":"Import external references used by `previous_definition`. It's usually resources not accessible by Bump servers, like local files or internal URLs.","items":{"$ref":"#/components/schemas/Reference"}},"definition":{"type":"string","description":"**Required** if `url` is not present.\nSerialized definition of the current version. This should be an OpenAPI 2.x, 3.x or AsyncAPI 2.x file\nserialized as a string, in YAML or JSON.\n","example":"{\"openapi\": \"3.0\", \"info\": { \"title\": … }}\n"},"references":{"type":"array","description":"Import external references used by `definition`. It's usually resources not accessible by Bump servers, like local files or internal URLs.","items":{"$ref":"#/components/schemas/Reference"}},"expires_at":{"type":"string","format":"date-time","description":"Public change expiration date and time. After this date, this documentation change will be destroyed.","example":"2022-02-22T22:20:22Z"}}}},"examples":{"CommonDiff":{"summary":"No formats","value":{"id":"2361df99-1234-4c80-a0cc-45c9fe565812","public_url":"https://bump.sh/diff/2361df99-3467-4c80-a0cc-45c9fe565812","breaking":false,"previous_version_url":"https://bump.sh/diff/2361df99-3467-4c80-a0cc-45c9fe565812/previous.json","current_version_url":"https://bump.sh/diff/2361df99-3467-4c80-a0cc-45c9fe565812/current.json"}},"DefaultDiff":{"summary":"Default response","value":{"allOf":[{"$ref":"#/components/examples/CommonDiff/value"},{"text":"Updated: POST /versions\n  Response modified: 201\n    Body attribute added: doc_id\n","markdown":"## Modified (1)\n\n* `POST /user`\n  * Path parameters added: `id`, `email`\n  * Query parameters added: `period`, `limit`\n"}]}},"HTMLDiff":{"summary":"HTML only response","value":{"allOf":[{"$ref":"#/components/examples/CommonDiff/value"},{"html":"\u003cul class=\"changelog-event__diff expandable\" data-expander-target=\"content\"\u003e\n  \u003cli class=\"changelog-event__diff-operation added\"\u003e\n     Added: \u003ca href=\"http://localhost:3000/diff/c1e36203-5b04-4adc-b8c5-8ac626ce8592#operation-get-diffs-parameter\"\u003e\u003ccode class=\"code-inline root\"\u003eGET /diffs/{id}\u003c/code\u003e\u003c/a\u003e\n  \u003c/li\u003e\n\u003c/ul\u003e\n"}]}},"JSONDiff":{"summary":"JSON only response","value":{"allOf":[{"$ref":"#/components/examples/CommonDiff/value"},{"details":[{"id":"post-versions","name":"POST /versions","status":"added","type":"endpoint","breaking":false,"children":[]}]}]}},"NewVersion":{"ExistingDocumentation":{"summary":"Create new version on an existing documentation","value":{"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"}},"CreatingStandaloneDocumentation":{"summary":"Create a new standalone documentation with the given version","value":{"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}},"CreatingDocumentationInHub":{"summary":"Create a new documentation inside a hub","value":{"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"}}}}}}