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/vendor group default account, eliminating the most common booking error. Full request/response shapes are in the API Reference.
How deprecation is signaled
Deprecation is signaled in two machine-readable ways:
- In the API Reference — deprecated operations carry the OpenAPI
deprecatedflag and a migration note in their description. - 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). |
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 |
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
Code
Monitor it and rotate the key before it lapses. See API Keys for creating and rotating keys.