# Versioning and deprecation

This policy explains how the DataSift APIs change and how much notice you get before a change can break your integration.

## API versions

Account and record-management endpoints use v2. SiftMap endpoints use v1; see the [SiftMap guide](/guides/siftmap-api) for its request URL and examples.

Within a major version, paths aren't versioned: `/api/internal/property/` stays `/api/internal/property/`.

## Non-breaking changes

These can ship at any time, without notice, and are listed in the [changelog](/guides/changelog):

- New endpoints, or new HTTP methods on existing endpoints
- New optional request fields or query parameters
- New fields in responses
- New values in enums, event types or status lists
- New optional headers
- Changes to the wording of error messages
- Documentation fixes that bring the reference in line with how the API already behaves


**Build for these.** Ignore response fields you don't recognize, don't depend on the order of fields or list items unless documented, handle enum values you don't know, and match errors on status codes and field names, not message text.

## Breaking changes

A change is breaking if a correctly built integration could stop working. For example:

- Removing or renaming an endpoint, field, parameter or enum value
- Changing a field's type or format
- Making an optional request field required
- Changing authentication, or the meaning of a status code
- Lowering a documented limit


## How breaking changes are introduced

1. **Announce.** The change is published in the changelog with a migration path, and affected operations are marked `deprecated` in the API reference.
2. **Notice period.** The old behavior keeps working for at least **90 days** after the announcement (**6 months** for removing a whole API version).
3. **Remove.** After the notice period, the old behavior can be removed. The removal is recorded in the changelog.


Where possible, deprecated endpoints also return `Deprecation` and `Sunset` response headers so your monitoring can detect them.

## Exceptions

A change may ship with shorter notice, or none, when it is needed to:

- Fix a security vulnerability or protect customer data
- Comply with a legal or regulatory requirement
- Stop usage that violates the [acceptable use](/guides/acceptable-use) policy or the Terms & Conditions


These changes are still recorded in the changelog.

## Beta features

Endpoints, fields or event types labeled **beta** in the reference can change or be removed without the notice period above. Don't build critical workflows on them until they reach general availability.

## Staying informed

- Watch the [changelog](/guides/changelog).
- Keep your contact email current in your DataSift account; breaking changes are also emailed to account owners who use the API.