> ## Documentation Index
> Fetch the complete documentation index at: https://help.honestly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Versioning and Backward Compatibility Guarantees

> Honestly's Export API follows semantic versioning. Learn how version increments work and what backward compatibility guarantees you can rely on.

The Honestly Export API follows semantic versioning and is designed to be backward-compatible whenever possible, so your integrations keep working as the API evolves.

## Current version

The current version of the Honestly Export API is **v1.3.0**.

## Versioning scheme

Version numbers follow the `MAJOR.MINOR.PATCH` format. Each component signals a different type of change:

* **MAJOR** — Incremented for breaking changes. All API consumers are notified and coordinated with in advance before a major version is released.
* **MINOR** — Incremented when new functionality is added in a backward-compatible way, such as new endpoints or new optional response fields.
* **PATCH** — Incremented for backward-compatible bug fixes or editorial changes that do not affect functionality.

## Backward compatibility guarantees

When Honestly increments a MINOR or PATCH version, the following guarantees apply:

* **New response fields are always optional.** Adding a field to a response will never break existing consumers that don't expect it.
* **Field semantics never change.** A field that represents a customer number will always represent a customer number — its meaning is stable across versions.
* **Validation rules on input fields are never made more restrictive.** A request that was valid before a patch or minor release will remain valid after it.
* **Enum output values use `x-extensible-enum`.** New enum values may be introduced over time. Your code should handle unknown enum values gracefully rather than failing.
* **URLs that must change will use `301` redirects.** If an endpoint path is moved, Honestly will issue a permanent redirect so existing integrations continue to function.

## Changelog

<AccordionGroup>
  <Accordion title="v1.3.0">
    Add `initiatives` endpoint to retrieve the account's initiatives (action items) as a paginated list with all of their data.
  </Accordion>

  <Accordion title="v1.2.0">
    Add `scores` endpoint to retrieve a single aggregated, anonymity-protected score for a set of questions over a time window.
  </Accordion>

  <Accordion title="v1.1.6">
    Add roles `Report viewer` and `Respondee` to the employee endpoint.
  </Accordion>

  <Accordion title="v1.1.5">
    Add `is_deleted` property to the employees list at the employees endpoint.
  </Accordion>

  <Accordion title="v1.1.4">
    Add `is_deleted` property to the questions list at the questions endpoint.
  </Accordion>

  <Accordion title="v1.1.3">
    Add `is_archived` parameter to the surveys endpoint.
  </Accordion>

  <Accordion title="v1.1.2">
    Add `current_survey_ends_at` property to the surveys list.
  </Accordion>

  <Accordion title="v1.1.1">
    Add `next_survey_starts_at` property to the surveys list.
  </Accordion>

  <Accordion title="v1.1.0">
    Endpoint `survey_assignments`: add `survey_id` property. Add versioning and backwards compatibility information. Change properties of type `enum` to `x-extensible-enum`. Add `is_deactivated` property to the surveys endpoint.
  </Accordion>

  <Accordion title="v1.0.0">
    Initial release.
  </Accordion>
</AccordionGroup>

<Note>
  If you have concerns about an upcoming breaking change, contact [service@honestly.com](mailto:service@honestly.com) — all major version changes are coordinated with API consumers in advance.
</Note>