Frequently asked questions

Bump.sh is a platform that publishes API documentation from OpenAPI and AsyncAPI documents, and hosts MCP servers built from API workflow documents. From an API definition, Bump.sh generates a documentation portal with an API explorer, an automatic changelog with breaking change detection, and AI-ready formats (Markdown pages, llms.txt, an MCP server). From a Flower or Arazzo workflow document, it deploys an MCP server that AI agents can call to run real API workflows. See the quick start to deploy your first document.

Bump.sh supports OpenAPI from version 2.0 (Swagger) to version 3.2, and AsyncAPI up to version 2.6. JSON Schema is supported inside both, including readOnly and writeOnly properties, enum and const. For MCP servers, Bump.sh accepts Flower and Arazzo workflow documents. Details and known limits are listed on the OpenAPI support and AsyncAPI support pages.

No. Bump.sh focuses on OpenAPI and AsyncAPI for API documentation, and on Flower and Arazzo for MCP servers. Other specifications may come later. If you need one, tell us about your use case.

Bump.sh offers a Pro plan and custom plans, billed monthly or annually, and every account starts with a 14-day free trial, no credit card required. Branches, the API Explorer and unrelease are part of the Pro plan. Custom plans add SSO, manual release, embed mode, head injection, advanced CSS customization, an on-premise data plane for MCP servers and a contractual SLA. Custom domains are available on every plan. Current plans and prices are on the pricing page.

Yes, in two ways. Every new account starts with a 14-day free trial of the platform when you sign up, with no credit card required. Without any account, the bump preview command of the CLI creates a temporary documentation with a unique URL, valid for 30 minutes, without any authentication. Add --live --open to refresh the preview each time you save the file. See the preview command.

There are four ways to deploy an API document to Bump.sh:

• Dashboard: upload the file from the documentation settings.
• CLI: npx bump-cli deploy openapi.yml --doc my-doc --token $BUMP_TOKEN (npm package bump-cli, Node 20+, or a standalone binary).
• GitHub Action: bump-sh/github-action@v1 with a BUMP_TOKEN secret.
• API: POST /versions on the Workspace API.

Each deployment is released automatically by default. See deploy and release management.

Yes. The CLI runs in any CI environment, and Bump.sh documents ready-made setups for GitHub Actions, GitLab CI, Azure DevOps, CircleCI and Travis CI. The CLI reads the BUMP_ID, BUMP_TOKEN and BUMP_HUB_ID environment variables, so tokens never appear in your scripts.

Run the deploy command with the --dry-run flag. Bump.sh validates the document against its specification and simulates the deployment without publishing anything. The GitHub Action offers the same through its command: dry-run input. See validate an API document.

Branches are parallel definitions of the same documentation, for example one per environment (staging, production) or per API version (v1, v2). Each branch has its own deployments and changelog, and readers switch between branches with a dropdown. The default branch is shown first and receives deployments that specify no target. Deploy to a branch with --branch in the CLI, the branch input of the GitHub Action, or branch_name in the API. Branches are a Pro plan feature. See branching.

Yes. With manual release, available on custom plans, deployments queue up with a preview and are only published when you release them, optionally with a title and a description. On the Pro plan, you can unrelease a version to roll back to the previous one. See manual release.

Yes. Bump.sh resolves internal references and external references to URLs or files, with absolute or relative paths, even where the specification does not allow them. Recursive references are limited to 5 levels. When uploading from the dashboard, file-system references cannot be resolved, so use the CLI or the GitHub Action for multi-file definitions. See references.

Yes. The CLI applies OpenAPI overlays with bump overlay, or directly during a deployment with one or several --overlay flags. See overlays.

Every release is compared with the previous one, and the differences become a changelog entry. Additions are shown in green, modifications in orange, deletions in red, and breaking changes are highlighted at the top of the entry. Any two entries can be compared, even across branches, and the comparison has a shareable URL. See changelog.

A breaking change is a change that can break existing API consumers. Bump.sh flags, among others:

• renaming or deleting an endpoint or a property, unless it was deprecated before,
• changing the type of a property,
• making an existing property required,
• adding or removing a security requirement,
• removing the polymorphism of a property.

See breaking change identification.

Consumers subscribe from the documentation with the “Get Updates” button, by email (at most one email a week) or RSS. For your own tooling, Bump.sh sends Slack notifications and signed webhooks (X-Bump-Signature-256 header, HMAC SHA-256) on every structural change. See integrations.

Yes. The GitHub Action posts a comment with the API diff on each pull request, and can fail the check when a breaking change is detected (fail_on_breaking). The CLI provides the same with bump diff, which fails on breaking changes by default in CI. See the GitHub Action and the diff command.

Yes. A private documentation requires authentication, is not indexed by search engines, and is accessible to the members of your organization and to external guests you invite. A private hub makes all its documentation private. Public documentation is open to everyone and indexed. See documentation access management.

Yes, on custom plans. SSO runs on WorkOS and supports generic SAML, SCIM, OpenID Connect, Okta, Auth0, Keycloak, Azure AD, Google SAML and more. Users signing in through SSO get the Viewer role by default, and the login page can be customized. See SSO.

Bump.sh only stores what you explicitly send: your API and workflow documents, and user information (name, email, role). Bump.sh never accesses your infrastructure or source code. The platform is protected by a WAF, continuous monitoring, daily dependency updates, staff security training and penetration tests conducted by customers. See security and confidentiality.

Yes. Bump.sh is a French company and complies with the GDPR. The Data Processing Agreement describes the data protection practices in detail.

Yes, on every plan. Create a CNAME record pointing to custom.bump.sh for a documentation or a hub, then enable the custom domain in the settings. SSL certificates are issued automatically. MCP servers use a CNAME to custom.run.bump.sh. See custom domains.

Yes. You can set the color scheme, logo, favicon and social image, with a dedicated logo and color for dark mode. Custom plans can go further with CSS variables. Navigation can be organized by path, by tag, or into custom sections with x-tagGroups. See branding customization.

Yes, on custom plans. Embed mode serves the documentation through your reverse proxy (Fastly, Cloudflare, CloudFront, Netlify Edge) and lets you inject your own head, top bar and footer, so the documentation lives on your site with your navigation. The headless Portal API also exposes list, search and fetch endpoints to build a fully custom portal. See embed mode and the Portal API.

Yes, on custom plans. Head injection adds your analytics or support scripts to every documentation page. See head injection.

Yes. Topics (x-topics) add Markdown pages such as guides, authentication walkthroughs or FAQs to the documentation, and their content can be pulled from .md files with $ref. Every description supports Markdown, with code blocks, callouts, images, accordions and Mermaid diagrams. See topics and Markdown support.

Yes. The API Explorer, available on the Pro plan, sends real requests to any server declared in the definition. It supports HTTP Basic and Bearer, API keys and OAuth2 authentication, server variables, and shareable pre-filled requests that never include credentials or responses. Requests go through an open-source CORS proxy that can be disabled. See the API Explorer.

An MCP server exposes tools that AI agents (ChatGPT, Claude, Cursor, and any Model Context Protocol client) can call. On Bump.sh, you describe API workflows in a document and Bump.sh hosts an MCP server that executes them, with no code to write and no infrastructure to run. Each execution follows the workflow definition exactly, so the behavior is deterministic. See MCP servers.

Use Arazzo, the OpenAPI Initiative workflow specification, when you already have OpenAPI documents to reference. Use Flower, the lightweight specification by Bump.sh, for quick prototyping, small projects, workflows calling APIs without an OpenAPI document, or when you need data transformation between steps. Both support multi-step sequences, retries, conditional flow and runtime expressions. See Flower support and Arazzo support.

No. The AI agent never calls your APIs directly. It invokes a tool on the MCP server, and an isolated data plane runs the workflow: it resolves secrets, executes the HTTP requests and returns only the declared outputs. Secrets are encrypted at rest with AES-256-GCM and decrypted in memory only, API responses are discarded after execution, and logs never contain secrets, request bodies or response payloads. See MCP server security.

You choose per server: public (anyone with the URL), private with a Bump.sh account (members of your organization), or private through your own OAuth server such as Okta, Auth0 or Keycloak, so your users sign in as they already do. See MCP server access management.

Yes. With Ask AI enabled, a public documentation or hub exposes an MCP server at its URL followed by /mcp, serves every page as Markdown by appending .md to its URL, and publishes an llms.txt index. Readers get an “Ask AI” menu to add the documentation to Cursor, VS Code, ChatGPT or Claude. See Ask AI capabilities.

A hub gathers several API documentation on a single page, sorted by categories, with a unified changelog and a search across all its APIs. Access, branding, sorting and API Explorer settings are managed once at the hub level. See hubs.

Three roles: Admin, Maintainer and Viewer. All three can access the documentation and hubs. Admins and Maintainers can manage documentation and hubs and invite external guests. Only Admins manage the organization and its members, and only the owner has access to billing. See organization access management.

Plans are billed monthly or annually, by credit card, through Stripe. Invoices are sent as PDF to the account email and to an optional extra address, and list your company name, address and VAT number. VAT is not applied outside Europe, and not applied in Europe when you provide a VAT number. See billing.

Support is provided by the Bump.sh team, never by a chatbot, for every plan, by email at hello@bump.sh or through the in-app chat. Bump.sh aims for above 99.9% availability, and commits to it with service credits on custom plans. Live and past incidents are on the status page, with notifications by email, Slack, RSS, SMS or webhook. See support and SLA.