# KDPBot API versioning and deprecation policy

The KDPBot REST API is versioned in the URL path. This page is the contract: it
states what can change without warning, what cannot, and how you will be told
before anything is removed.

Machine-readable surface: [openapi.json](https://kdpbot.com/openapi.json) ·
[openapi.yaml](https://kdpbot.com/openapi.yaml) ·
[agent guidance](https://kdpbot.com/llms.txt)

## Current KDPBot API version

| | |
|---|---|
| Current version | **v1** |
| Recommended base URL | `https://kdpbot.com/api/v1` |
| Origin base URL | `https://bookgen-backend-5zuf.onrender.com/api/v1` |
| Unversioned alias | `https://kdpbot.com/api` |

Both base URLs serve the same application. `kdpbot.com/api` proxies to the
origin, which keeps the API same-origin with the web app and discoverable from
the main domain. Either is supported; prefer `kdpbot.com/api/v1`.

Trailing slashes are **mandatory** on every path. A request to a slashless path
is redirected by Django's `APPEND_SLASH`, and a redirected POST loses its body.

## The unversioned `/api/` prefix

`/api/…` is a permanent alias of the **current** version. It exists for clients
written before versioning was introduced and will keep working.

It is, however, a moving target by definition: when a future v2 becomes current,
`/api/` follows it. If you are writing a new integration — and especially if you
are an autonomous agent that will not be re-tested by a human — pin `/api/v1/`.

## KDPBot version headers on every response

| Header | Meaning |
|---|---|
| `X-API-Version` | The version that served this response, e.g. `1` |
| `X-API-Version-Latest` | The newest version available |

If `X-API-Version-Latest` is greater than `X-API-Version`, a newer surface
exists and you are running against an older one. Nothing is broken — this is an
advisory signal so you can schedule a migration instead of discovering it at
sunset.

## How deprecation is announced

When a version is scheduled for removal, every response from that version
carries the standard headers:

| Header | Meaning |
|---|---|
| `Deprecation` | HTTP-date at which the version became deprecated |
| `Sunset` | HTTP-date at which the version stops being served ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) |
| `Link: <…>; rel="deprecation"` | URL of the migration notes |

Example:

```http
HTTP/1.1 200 OK
X-API-Version: 1
X-API-Version-Latest: 2
Deprecation: Wed, 01 Jan 2031 00:00:00 GMT
Sunset: Thu, 01 Jul 2031 00:00:00 GMT
Link: <https://kdpbot.com/docs/versioning.md>; rel="deprecation"
```

**Guarantee: `Sunset` is set at least six months in the future.** You will never
get less than six months of notice on a live endpoint.

### What an agent should do

1. Read `Sunset` on every response. If it is present, schedule a migration.
2. Do not fail closed just because `Deprecation` is set — a deprecated version
   still works until its `Sunset` date.
3. Treat a `410 Gone` on a previously working path as a version that has passed
   its sunset. Re-read this page and the OpenAPI document.

## What may change inside a version

These are **not** breaking and can ship at any time, so your client must
tolerate them:

- **New fields added to a response.** Ignore fields you do not recognise.
- **New optional request fields.**
- **New endpoints, new enum members, new error codes.** Branch on
  `error.code` with a default branch — never assume the set is closed.
- Ordering of a list where no order is documented.
- Performance, rate-limit values, and the wording of `error.message`.

## What will not change inside a version

- A path or HTTP method being removed or repurposed.
- A field being removed from a response, or its type changing.
- A field becoming required when it was optional.
- The meaning of an existing `error.code`.
- The authentication scheme.

Anything in this list requires a new major version.

## KDPBot API errors and rate limits

The error envelope and the `RateLimit-*` headers are part of the versioned
contract:

- [Error codes and the JSON envelope](https://kdpbot.com/docs/errors.md)
- [Rate limits and backoff](https://kdpbot.com/docs/rate-limits.md)

## More KDPBot AI documentation

- [Quickstart](https://kdpbot.com/docs/quickstart.md) · [Authentication](https://kdpbot.com/docs/authentication.md) · [Errors](https://kdpbot.com/docs/errors.md) · [Rate limits](https://kdpbot.com/docs/rate-limits.md) · [API reference](https://kdpbot.com/docs/api.md)
- [MCP and agent integration](https://kdpbot.com/docs/mcp.md) · [Agent instructions](https://kdpbot.com/agents.md) · [llms.txt](https://kdpbot.com/llms.txt)
- [KDPBot OpenAPI specification (JSON)](https://kdpbot.com/openapi.json) · [OpenAPI 3.1 (YAML)](https://kdpbot.com/openapi.yaml) · [KDPBot developer portal](https://kdpbot.com/developers/) · [API catalog](https://kdpbot.com/.well-known/api-catalog)

## Questions

Email [support@kdpbot.com](mailto:support@kdpbot.com), or reach us on
[Telegram](https://t.me/blabla_ecommerce). If you maintain an integration and
want advance notice of version changes, say so in that email and we will contact
you directly before any sunset.