An API changelog for integrators must let a reader decide, from one entry and in under a minute, whether they have to change their own code. That takes six fields per entry: what changed, whether it breaks, from when, which endpoint, what to do about it, and what the entry is based on. Most published changelogs carry the first one and a date.
The rest of this article takes one entry apart, field by field, and then asks where each field can come from without anyone typing it twice.
Why an API changelog is not a product changelog
API changelog: the dated record of changes to an API's contract and behavior, written for the people and programs that call it, and organized around the decision "do I need to act?".
A product changelog tells customers what is new. It is read for pleasure, or skipped, and nothing bad happens if it is skipped. An API changelog is read under a different pressure: someone is about to upgrade, or a nightly job just failed, and the reader wants to know whether the log explains it.
That changes what a good entry looks like. A new settings page is good news for a product changelog. For an API changelog, the same week's most important line may be "the default page size went from 50 to 25", which no customer-facing note would ever mention. The unit is not the feature. It is the change a caller could notice.
This is the artifact side of a question we treat separately: how to answer "did the API change this week?" from the diffs. Here the question is the document an integrator can subscribe to instead of asking.
Anatomy of one entry
Below, one entry in the shape we recommend. The endpoint, dates and names are illustrative, not taken from any customer.
| Field | What it holds | In the example |
|---|---|---|
| 1. Change | One sentence in the caller's vocabulary | GET /invoices now returns client_id instead of customer_id. |
| 2. Class | Breaking, additive, behavioral, or deprecation | Breaking |
| 3. Effective | The date it reached production, not the date it was announced | 2026-09-14 |
| 4. Scope | Endpoints, fields or parameters touched | GET /invoices, GET /invoices/{id}: response field |
| 5. Action | What the integrator does, or "none" | Read client_id. customer_id is not returned. |
| 6. Basis | What the entry was derived from | The serializer change, commit of 2026-09-14 |
Each field closes a specific doubt.
Change is the headline, and it is the only field most changelogs have. Write it from the caller's side: what the response now contains, not what the team refactored.
Class is the triage field. A reader scanning twenty entries should find the breaking ones without reading prose. Four classes are enough. Breaking forces a code change. Additive adds something optional. Behavioral changes a default, a sort order or a limit without changing a shape. Deprecation announces a future removal. Behavioral is the one teams forget, and it is the one that fails silently.
Effective is where changelogs lie by omission. "Announced on the 28th" and "live on the 14th" are different facts, and an integrator debugging the failure of the 15th needs the second one. If the announcement came late, say so in the entry; the log is more useful with an uncomfortable date than with a flattering one.
Scope lets a reader answer "does this touch me?" without opening the reference. Someone who only calls POST /payments can stop reading at this line.
Action is the line integrators remember a changelog for. "None" is a valid and valuable value: it tells a reader they can stop. If a migration takes more than a sentence, link to the guide rather than inlining it.
Basis is the unusual one. It says what the entry rests on: a diff, a commit, a spec change. It is what separates a log that was written from memory from one that can be checked. A reader who doubts an entry can follow it back; a log that never says where its claims come from asks to be trusted instead.
Deprecations need two dates
An entry announcing a removal carries a second date: when the thing stops working. The HTTP Sunset header (RFC 8594) and the Deprecation header (RFC 9745) exist to say the same thing in each response, and an entry in the changelog should match what those headers say. A changelog that announces a sunset the headers do not mention, or the reverse, gives integrators two sources to reconcile.
A removal with no date is not a deprecation. It is a rumor with a link.
What actually keeps a changelog accurate
Writing six fields by hand for every change is exactly why API changelogs decay: the effort lands at the worst moment, right after a merge, and the first field skipped is the awkward one (the class, the effective date, the line that admits a break). Two fields never need typing at all.
Scope and basis are facts about the diff. Which endpoint, which field, which commit: the modification itself holds them. The class is largely derivable too: a removed field in a serializer is breaking, a new optional parameter is additive, a changed default is behavioral. A human still decides the edge cases and writes the action line. Nobody should have to type what the code already says.
This is the approach DeployIt takes: it reads the real code (resynced on every push) and the git history (commits and diffs), and checks the code before asserting anything. A changelog entry is then a published view of the same source that answers questions in a chat. The changelog generated from git history covers the general mechanism; the API case is the same mechanism held to the six fields above. And because the expert is also exposed as an MCP server, an integrator's agent can ask "what changed in the invoices API since v2.3?" instead of scraping the page.
A short test before you publish
Take the last five entries of your current API changelog and ask, for each:
- Can a reader tell whether it breaks, without reading the pull request?
- Is the date the one on which production changed?
- Could someone who calls only one endpoint stop reading after the scope line?
- Is there an action line, even if it says "none"?
- If the entry turned out to be wrong, could anyone find out what it was based on?
Two "no" answers on the same entry mean it is a news item, not an API changelog entry. That is fine for a blog. It is not what an integrator needs on the morning a job fails.
"Our OpenAPI diff already produces this"
Keep it. A spec diff in CI is a good source for fields 1 to 4 on every contract change it can see, and nothing here asks you to drop it. Its limit is the one that makes the class field worth having: a spec describes shapes, so a changed default, a tightened validation or a modified sort order does not appear in it. Those are the behavioral entries, and they are the ones that fail silently. Deriving entries from the code's diffs covers them too, and the spec stays what it is: one input among others.
The other limit is who can read what. A spec diff lives in your CI. The changelog is the part your integrators can actually see.
What DeployIt needs to see, and what the entry shows
Read-only GitHub connection, one server per project, revocable at any time. The entries expose what changed (a field, an endpoint, a default), never the source around it. An integrator learns that customer_id became client_id; they do not read your serializer. The code stays in the repository.
Three frequent questions
Should the changelog be a page, a feed, or both? Both, if you can. A dated page is what a person finds; a feed or a machine-readable list is what a script or an agent subscribes to. Keep them one source, so they cannot disagree.
How far back should it go? As far as your oldest supported version. An integrator pinned to a version from a year ago needs the entries since that version, not the last month.
Does every change get an entry? Every change a caller could notice. Internal refactors that leave the contract and behavior untouched do not belong, and a log full of them buries the entry that matters.
Where to start
Do not rewrite the history. Apply the six fields to the next release, derive what can be derived, and write the action line yourself. In a month you will have a changelog an integrator can decide from.
DeployIt's MCP server is in early access / design partner program: if your integrators ask you what changed faster than you can write it down, the program is open. DeployIt is free during early access; paid plans arrive in January 2027. For the documentation side of the same source, see how a help center stays in sync with releases, how to detect documentation drift and the DeployIt help center.
Continue reading
Can you generate Notion documentation from your code without overwriting what your team writes?
Generating Notion documentation from code is the easy part; making it coexist with what your team writes by hand is the real problem. The four writing rules that decide whether the page survives.
How do you build a "What's new" page generated from git?
A "What's new" page is not a changelog with better styling: its window belongs to the reader, not to the release. What you have to derive from diffs to make it work, and the triage that remains.
How do you detect documentation drift?
You do not find a stale page by rereading it. You start from the diffs of the period and work back to the pages they invalidated. The manual audit, its blind spots, and continuous detection.