> For the complete documentation index, see [llms.txt](https://docs.saas.haut.ai/haut.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saas.haut.ai/haut.ai/developers/api-breaking-and-non-breaking-changes-guide.md).

# API Breaking and Non-breaking Changes Guide

What counts as a breaking change to a Haut.AI API response, what does not, and how to build an integration that survives both.

This guide helps you understand what constitutes a breaking and non-breaking change in our API responses and how to future-proof your integrations.

## Our Commitment

**For breaking changes, we will notify all clients at least 1 month prior to implementation.** This gives you time to update your integrations before the changes take effect.

## What We Consider Breaking Changes

These changes could break integrations and require updates to your code.

### 1. Removing or renaming fields

* Removing parameters (e.g., `redness`, `puffiness`, `ita`).
* Renaming keys (e.g., `score` → `value`, `tag` → `label`).

**Impact:** Code that accesses these fields by name will fail.

### 2. Changing data types

* Converting `score: number` to `score: string`.
* Converting `grade: number` to `grade: object`.

**Impact:** Strongly typed languages will fail at runtime or compile time.

### 3. Changing nullability

* Fields that were always present become optional or `null`.

**Impact:** Code that doesn't perform null checks may crash.

### 4. Restructuring nested objects

* Moving fields (e.g., `parameters.redness.score` → `parameters.redness.metrics.score`).
* Changing object nesting levels.

**Impact:** JSON path lookups and data bindings will break.

### 5. Changing field semantics

* Score scale changes (e.g., 0–100 → 0–1).
* Grade interpretation changes (e.g., 1 = best → 1 = worst).

**Impact:** Business logic and UI interpretations will be incorrect.

### 6. Removing supported variants

* Dropping specific views (e.g., `left`, `right`).
* Removing mask types (e.g., `anonymised`).

**Impact:** Integrations relying on specific data variants will fail.

### 7. Changing enum values

* Modifying enum formats (e.g., `"very light"` → `"VeryLight"`).
* Adding unexpected enum values without documentation.

**Impact:** UI mappings to labels, icons, or colors will break.

### 8. Changing mask output format

* Switching mask format (e.g., `png` → `svg`).

**Impact:** Integrations expecting specific formats will fail to process responses.

## What We Consider Non-Breaking Changes

These changes are safe and backward compatible. We may implement them without advance notice.

### 1. Adding new parameters

* New top-level parameters (e.g., `hydration`) can be safely ignored by existing clients.

### 2. Adding optional fields

* New fields added to existing objects are safe if existing fields remain unchanged.

### 3. Adding new mask formats

* Adding formats (e.g., `webp` alongside `svg`/`png`) while maintaining existing ones is safe.

### 4.Improving algorithm quality and precision

* Improvements to algorithm accuracy that result in slightly different numeric values (e.g., `score: 84` → `score: 85`) are considered non-breaking as they enhance the quality of results without changing the response structure or data types.

### 5. Visual improvements

* Updating mask colors or styling for better visibility.
* Improving mask accuracy or quality.

## Best Practices for Integration

To minimize impact from API changes:

* Implement parsing that ignores unknown fields.
* Perform null checks on all nested fields.
* Use semantic versioning and version pinning.
* Check [changelog](/haut.ai/releases/changelog.md) for updates.

***

{% hint style="warning" %}
Not a Haut.AI client yet?
{% endhint %}

<a href="https://haut.ai/book-a-demo?utm_source=referral&#x26;utm_medium=saas_docs&#x26;utm_campaign=Docs_SaaS_HautAI" class="button primary" data-icon="user-vneck">Book a demo</a> <a href="https://haut.ai/product/ai-skin-analysis?utm_source=referral&#x26;utm_medium=saas_docs&#x26;utm_campaign=Docs_SaaS_HautAI" class="button secondary" data-icon="external-link">Platform overview on haut.ai</a>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.saas.haut.ai/haut.ai/developers/api-breaking-and-non-breaking-changes-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.