# Versioning & Deprecation

The Public API is versioned in the URL path. All endpoints live under the base
URL `https://api.ledgerbee.com/api`, followed by the version segment. Most of
the surface is `/v1` (e.g. `GET /api/v1/company`); a few journal-entry
endpoints have `/v2` successors.

## Stability within a version

Within a major version the API is **additive-only**:

- New fields may appear in responses at any time. Parse leniently and ignore
  fields you don't recognize.
- Existing fields are never renamed, removed, or retyped.

Breaking changes ship only as a new version under a new path segment, leaving
the old version running.

## Current `/v2` endpoints

| v2 endpoint | Replaces |
|---|---|
| `POST /api/v2/journal-entries` | `POST /api/v1/journal-entries` |
| `POST /api/v2/journal-entries/batch` | `POST /api/v1/journal-batches` |
| `POST` / `GET /api/v2/draft-journal-entries` (+ `/{id}`, `/{id}/book`) | the `/api/v1/draft-journal-entries` equivalents |
| `POST /api/v2/draft-journal-batches` | `POST /api/v1/draft-journal-batches` |

The v2 journal-entry endpoints auto-append the AR/AP leg on the
customer/supplier group default account, eliminating the most common booking
error. Full request/response shapes are in the [API Reference](/api).

## How deprecation is signaled

Deprecation is signaled in two machine-readable ways:

1. **In the API Reference** — deprecated operations carry the OpenAPI
   `deprecated` flag and a migration note in their description.
2. **On the wire** — endpoints with a scheduled shutdown tag every response
   with three headers:

| Header | Example value | Meaning |
|---|---|---|
| `Deprecation` | `true` | The endpoint is deprecated (draft IETF deprecation header). |
| `Sunset` | `2026-11-08` | Date after which the endpoint may stop working ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)). |
| `Link` | `</api/v2/draft-journal-entries>; rel="successor-version"` | Where to migrate. |

Deprecated endpoints function normally until their sunset date; the headers
are informational only. Log a warning whenever your client sees a
`Deprecation` header so migrations surface before the sunset.

## Currently deprecated endpoints

| Endpoint | Migrate to | Sunset |
|---|---|---|
| `POST /api/v1/journal-entries` | `POST /api/v2/journal-entries` | none scheduled — stays available for legacy integrators |
| `POST /api/v1/journal-batches` | `POST /api/v2/journal-entries`, one call per entry | none scheduled |
| `/api/v1/draft-journal-entries` — create, list, get, book, delete | `/api/v2/draft-journal-entries` | **2026-11-08** |
| `/api/v1/vendors` — all operations (list, groups, contacts, departments, create) | `/api/v1/suppliers` — identical shapes with supplier-named fields and `SUPPLIER_*` error codes | none scheduled — the alias keeps serving legacy field names and `VENDOR_*` codes |
| `POST /api/v1/draft-journal-batches` | `POST /api/v2/draft-journal-batches` | **2026-11-08** |

The v1 draft endpoints emit the `Deprecation` / `Sunset` / `Link` headers on
every response (the `Link` successor points at `/api/v2/draft-journal-entries`,
or `/api/v2/draft-journal-batches` for the batch route).
The two v1 journal-entry write endpoints emit `Deprecation` and `Link` but no
`Sunset` header — they are deprecated without a scheduled shutdown.

## API key expiration header

When you authenticate with an API key that has an expiry date, every response
carries

```
X-API-Key-Expires-At: 2026-12-31T23:59:59.000Z
```

Monitor it and rotate the key before it lapses. See
[API Keys](/guides/api-keys) for creating and rotating keys.