---
title: "Public API Versioning and Deprecation"
description: "The Public API has one unversioned endpoint. Published fields never break: changes are additive, and removals are deprecated with a date first."
canonical_url: https://chatfuel.com/docs/public-api/versioning
markdown_url: https://chatfuel.com/docs/public-api/versioning.md
last_updated: 2026-10-06
lang: en
site: https://chatfuel.com/docs
llms_txt: https://chatfuel.com/llms.txt
---

# Public API Versioning and Deprecation

The Public API has one unversioned endpoint. Published fields never break: changes are additive, and removals are deprecated with a date first.

The Chatfuel Public API has a single endpoint, `https://panel.chatfuel.com/graphql`, with no version number in the URL or headers. Instead of versions, it follows one rule: a published field never changes in a way that breaks existing clients. New capabilities are added alongside the old ones, and anything that has to go is deprecated with a removal date first.

## What the public schema guarantees [#what-the-public-schema-guarantees]

The public schema is the contract between Chatfuel and your integration. It contains only fields that Chatfuel has explicitly published for external use; the rest of the GraphQL API used by the dashboard is internal and is not available to rely on. Once a field is published, Chatfuel:

* doesn't remove it or rename it without the deprecation process below
* doesn't change its type or make an optional argument required
* doesn't remove input fields you can send

## Changes that can happen at any time [#changes-that-can-happen-at-any-time]

Additive changes are not breaking and can ship without notice:

* new queries, mutations, subscriptions and fields
* new optional arguments and input fields
* new values in enums, for example a new `Platform` or a new sales stage
* new types in unions and new implementations of interfaces, for example a new message type in a conversation

Write clients that tolerate these changes. Select only the fields you need, handle unknown enum values with a default branch, and skip union members and message types your code doesn't know.

## How deprecation works [#how-deprecation-works]

Removing a published field takes three steps:

1. The field gets a GraphQL `@deprecated` mark with a reason in a fixed format: "Stop using by YYYY-MM-DD. Use X instead." A public replacement ships at the same time, if one is needed. The field keeps working normally.
2. After the stated date, the field is hidden from the public schema. Requests that still select it fail with a validation error.
3. Later, the field is deleted.

The date in the reason is the last day you can count on the field. Until then, migrating to the replacement is safe at any time, because both work in parallel.

## How to stay up to date [#how-to-stay-up-to-date]

Deprecations are listed on the reference pages next to the affected operation, with the date and the replacement. Check the reference for the operations your integration uses when you plan maintenance. If a code generator in your project produces types from the schema, regenerate them after updating the schema file you build against, so the compiler shows any deprecated field you still use.

Changes in a published field's behavior that keep its shape, such as a new validation rule, appear as new error codes. Handle unknown error codes as a generic failure, as described in [errors](https://chatfuel.com/docs/public-api/errors).

## Common issues [#common-issues]

### A query that worked yesterday fails because a field is not defined [#a-query-that-worked-yesterday-fails-because-a-field-is-not-defined]

The field passed its deprecation date and was hidden, or the query selects a field that was never part of the public schema. Compare the query with the reference pages and use the documented replacement.

### My code breaks on a value it doesn't know [#my-code-breaks-on-a-value-it-doesnt-know]

An enum or union got a new member, which is an additive change. Add a default branch so new values are logged and ignored instead of crashing the integration.