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

# Response fields & versioning

> How Nedzo decides which fields appear in public API responses, our stability guarantees, and how fields are deprecated and removed.

This page is the contract for what you can rely on in Nedzo API responses, and how
we evolve those responses over time. It applies to every `/v1/*` endpoint.

## Allow-listed responses

Every public response is built from an explicit **allow-list** of documented fields.
A response contains the fields shown in that endpoint's reference page — and nothing
else.

Concretely, this means:

* **Internal fields are never returned.** We do not expose identifiers for our
  sub-processors or infrastructure (telephony, voice, LLM, RAG/knowledge-base,
  email, payment, and verification providers), internal feature flags, internal
  tokens or secrets, or our region-specific provider identifiers. These are
  implementation details that can change at any time without notice.
* **What you see is the whole contract.** If a field is not documented on the
  endpoint's reference page, do not depend on it — even if you observe it in a
  response during a transition. Treat undocumented fields as absent.
* **New fields may be added.** We may add new documented fields to a response at any
  time. Write clients that ignore unknown fields rather than rejecting them.

<Note>
  Because internal provider identifiers are never exposed, you can build on the Nedzo
  API without coupling to the specific vendors we use behind the scenes. We can change
  providers — including using different processors per region for data-residency
  reasons — without breaking your integration.
</Note>

## Field stability

| Change                              | Notice    | Notes                               |
| ----------------------------------- | --------- | ----------------------------------- |
| New documented field added          | None      | Clients must ignore unknown fields. |
| Internal/undocumented field removed | None      | Was never part of the contract.     |
| Documented field removed or renamed | ≥ 60 days | Breaking change — see below.        |
| Endpoint removed                    | ≥ 60 days | Breaking change — see below.        |

## Deprecation & removal

Removing or renaming a **documented** field, or removing an endpoint, is a breaking
change. We follow a fixed process:

1. **Pre-announcement** in the [changelog](/api-reference/introduction) and to
   affected integrations.
2. A **deprecation window of at least 60 days** during which the field or endpoint
   keeps working unchanged.
3. **Removal** only after the sunset date passes.

During the window, every affected response carries standard HTTP headers so you can
detect deprecations programmatically:

```http theme={null}
Deprecation: Wed, 11 Jun 2026 00:00:00 GMT
Sunset: Sat, 15 Aug 2026 00:00:00 GMT
Link: <https://docs.nedzo.ai/api-reference/changelog>; rel="deprecation"; type="text/html"
Warning: 299 - "The `foo` field is deprecated; use `bar`. Removal: 2026-08-15."
```

* `Deprecation` (per the IETF deprecation-header draft) — when the deprecation took
  effect.
* `Sunset` ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) — the date on or
  after which the field/endpoint will be removed.
* `Link; rel="deprecation"` — the changelog entry with migration guidance.

We recommend logging any response that carries a `Sunset` header so deprecations
surface during your normal monitoring.

## How we enforce this

The allow-list is enforced in code, not by review alone: every `/v1/*` response is
serialized through a central allow-list, and a CI gate fails any build that
introduces an internal-only field name into a public response, re-opens a response
schema to arbitrary fields, or bypasses the allow-list serializer. This is why you
can trust that the documented fields are exhaustive.