ChatbotGen API versioning and deprecation policy

How the API is versioned

The version lives in the URL path. Everything published today is version 1 and is served under https://www.chatbotgen.com/api/tools and https://www.chatbotgen.com/mcp. A breaking change takes a new path prefix rather than changing what an existing one means, so a request that works today keeps working or fails loudly — never quietly differently.

Every response carries the full semantic version in an API-Version header, and https://www.chatbotgen.com/api reports it under versioning.current. Read either one rather than inferring the version from the shape of a response.

curl -sSI https://www.chatbotgen.com/api | grep -i api-version
# api-version: 1.0.0

Changes we make without notice

These are additive and cannot break a client that ignores what it does not recognise. Write your integration so they cannot break yours either: parse JSON leniently, ignore unknown fields, and never assume the order of an array or the exact wording of a message.

New endpoints. New optional request fields. New fields in a response body. New values in an enumeration whose purpose is to grow, such as an error code or a training status. New response headers. Changes to prose: any message, hint, summary or description.

The code field of an error is the one thing in an error body that never changes wording. Branch on it, never on message.

Changes that take a new version

Removing or renaming an endpoint, a request field, or a response field. Making an optional request field required. Changing the type of a field, or the meaning of a value. Removing a value from an enumeration a client branches on. Tightening a limit in a way that rejects requests we used to accept.

Any of these ships under a new path prefix. The previous prefix keeps answering for the whole notice period below.

How a removal is announced

From the moment a surface is deprecated until the moment it stops answering, every response it sends carries three things: a Deprecation header (RFC 9745) with the timestamp at which it was deprecated, a Sunset header (RFC 8594) with the date it stops answering, and a Link header with rel="successor-version" naming what to move to.

The same information is in https://www.chatbotgen.com/api under versioning.deprecations, and the operation is marked deprecated: true in https://www.chatbotgen.com/openapi.json. An automated client can watch for any of the three without a person reading a changelog.

When that list is empty — as it is today — nothing published is scheduled for removal. That is a fact we publish, not a field we left out.

# A deprecated surface would answer like this. Nothing does today.
#   deprecation: @1767225600
#   sunset: Sat, 01 Jan 2028 00:00:00 GMT
#   link: <https://www.chatbotgen.com/api/v2/tools/sessions>; rel="successor-version"

curl -sS https://www.chatbotgen.com/api | jq .versioning.deprecations
# []

Notice periods

A deprecated endpoint keeps answering for at least six months after the Deprecation date, and the Sunset date is never brought forward once published. If it moves at all, it moves later.

A security or abuse problem is the one exception: if an endpoint has to be closed to stop harm, we close it and email the account owners of every integration we can identify. Nothing else short-circuits the notice period.

Deprecations are announced by email to account owners with an API key, and on this page. If you integrate without an account — the demo API and anonymous MCP need no key — watch the headers, which is why they are there.

What is not covered

The dashboard under /app is not an API. It answers Inertia, it needs a browser session, and it is deliberately absent from the OpenAPI document. It changes whenever the product does.

The free demo API under /api/tools is a public, keyless surface with hard caps, offered as-is for the free tools at https://www.chatbotgen.com/tools. It follows this policy, but its caps and its models are tuned as costs move — those are limits, not contract.

The MCP protocol version is negotiated per session and follows the Model Context Protocol's own release cycle rather than ours. The versions we accept are listed at https://www.chatbotgen.com/.well-known/mcp.json.