How to write release notes for APIs
Make contract changes testable for client maintainers.
01Identify the contract, not just the deployment
Name the API revision, affected endpoints and SDK versions separately. A server deployment number is not necessarily a public contract version. Record which clients must take action and which remain compatible.
02Show request and response differences
For every renamed field, show its old path, new path, type and nullability. Explain pagination, authentication and error-code changes explicitly; these often break integrations without changing a successful response example.
03Provide an ordered migration
Start with prerequisites, then update dependencies, configuration and call sites. Include a representative request and an assertion against the response. If old and new clients must coexist, document the compatibility window.
04Publish reusable upgrade facts
Record breaking-change summaries, affected surfaces and migration steps as structured fields, not only prose. LogPulse exposes maintainer-published release data over JSON and a public MCP server; the agent still needs to inspect and test the actual client code.
Before and after
Too vague
API v2 is faster. Upgrade now.
Specific and actionable
API 2.0.0: GET /events now returns {items, next_cursor}, not an array. Replace response.map(...) with response.items.map(...), follow next_cursor until null, and test an account with more than one page.
Fictional example — use your own verified names, versions and behavior.
Before you publish
- Identify API and SDK versions separately
- Check empty and paginated responses
- Document error and auth changes
- Verify example requests against a test environment
Common questions
Keep reading
LogPulse
Changelogs coding agents can upgrade from.
Publish versions, breaking changes, migration steps and deprecations once. People get a widget and hosted changelog; agents get a JSON feed and MCP server. Free for open source.