Changelogs for AI Agents: Why /changelog Matters for D8 Reliability
When an AI agent calls your API and gets a 500 error, it needs to know: is this a bug, a temporary outage, or a breaking change you shipped yesterday? Without a structured changelog, the agent has no way to tell. Stripe, GitHub, and Vercel all have public changelogs — and all score Silver or higher. That is not a coincidence.
The Silent Failure: When Agents Cannot Tell Bugs from Breaking Changes
An AI agent managing a customer's subscription calls your POST /api/subscriptions endpoint. Yesterday it worked. Today it returns a 500 error. The agent has three options:
- Retry — maybe it is a transient server error
- Adapt — maybe the endpoint moved or the schema changed
- Report failure — tell the user something is broken
Without a changelog, the agent guesses. It retries 3 times, gets 500 each time, and reports failure to the user. The user switches to a competitor. But the real cause was a breaking change you deployed at 2 AM — the endpoint now requires a billing_cycle field that did not exist before. A changelog with that information would have let the agent adapt its request in real time.
This is not hypothetical. As API versioning becomes more important in the agent economy, the changelog is the communication channel that makes versioning useful. Versions tell agents which API to call. Changelogs tell agents why the old call stopped working and how to update.
Who Does Changelogs Right: The Silver+ Pattern
Every business that scores Silver or higher on the Agent Readiness Score has a public changelog. This is one of the clearest correlations in our data — not because the changelog alone drives the score, but because companies that maintain public changelogs also maintain the kind of reliability infrastructure that agents depend on.
Stripe
Score 68 — SilverURL: stripe.com/docs/changelog
Format: HTML + structured API changelog, dated entries, version tags, breaking change labels
Agent value: Agents can detect breaking changes before retrying failed calls. Migration guides explain how to update.
GitHub
Score 65 — SilverURL: github.blog/changelog
Format: Blog-style changelog, category tags (API, Actions, Security), RSS feed
Agent value: Agents subscribe to RSS for real-time awareness of API changes. Category tags let them filter for relevant updates.
Vercel
Score 69 — SilverURL: vercel.com/changelog
Format: Date-grouped entries, visual cards, product area tags, linked documentation
Agent value: Each entry links to updated documentation. Agents can follow the link chain from "what changed" to "how to use the new version."
Average SaaS
Score 35 — Not ScoredURL: None or blog post buried in /news
Format: No dedicated changelog. Occasional blog post titled "Product Update Q1 2026" with marketing language
Agent value: Agents cannot find or parse marketing-style update posts. No structured data, no version numbers, no breaking change indicators.
The Structured Changelog: JSON, Not Just HTML
A beautiful HTML changelog page is good for humans. But agents need machine-readable data. The highest-scoring approach is a JSON changelog endpoint alongside the human-readable page. When an agent hits /api/changelog, it gets structured data it can parse, filter, and act on.
Recommended schema for /changelog or /api/changelog
The critical fields are type and affected_endpoints. When an agent filters for type: "breaking" and finds the endpoint it just failed on, it knows exactly what happened and can follow the migration guide to adapt. Without these fields, the agent is reading prose and guessing.
Semantic versioning matters too. An agent that knows you went from v2.3.1 to v3.0.0 understands a major breaking change occurred. A jump from v2.3.1 to v2.3.2 signals a patch — the agent can safely retry.
The deprecation date field is powerful:Agents can proactively warn users that an integration will break on a specific date, weeks before it happens. “Your subscription management integration with Acme Corp will break on June 15 when they remove the v1 API. I can update the integration now or remind you closer to the date.” No changelog = no warning = sudden failure.
How Changelogs Affect Your Agent Readiness Score
D8 Reliability carries a weight of 0.13 — making it the second-highest weighted dimension in the AgentHermes scoring formula. A changelog directly contributes to D8, but it also creates a halo effect on other dimensions.
D8 Reliability (direct)
+5-12 pointsStructured JSON changelog with version, type, and affected_endpoints scores highest. HTML-only changelog with dates scores lower but still contributes.
D2 API Quality (indirect)
+3-8 pointsChangelogs that document API endpoints, request/response schemas, and error codes serve as supplementary API documentation that agents can reference.
D9 Agent Experience (indirect)
+2-5 pointsA changelog at a well-known URL (/changelog) is a signal of developer maturity that D9 rewards. It indicates the business is thinking about programmatic consumers.
The combined effect of a well-structured changelog can add 10-25 points to your Agent Readiness Score. For a business sitting at 35 (Not Scored), adding a changelog alongside a status page and proper error handling can push them into Bronze territory (40+). For a business at 55, the changelog might be the difference between Bronze and Silver.
Building Your Changelog in 30 Minutes
You do not need a complex system. A static JSON file at /api/changelog that you update with each deployment is enough to score well on D8 and give agents the information they need. Here is the minimum viable changelog.
Create /changelog.json in your public directory
Static JSON file with an array of changelog entries following the schema above. Start with your last 10 releases.
Add type and affected_endpoints to each entry
These are the fields agents use most. "feature" and "fix" are safe. "breaking" and "deprecation" trigger agent adaptation logic.
Set up /changelog as a human-readable HTML page
Render the same data as a formatted page for human visitors. Link it from your footer, docs, and status page.
Automate updates from your CI/CD pipeline
Parse conventional commit messages (feat:, fix:, BREAKING CHANGE:) and append to changelog.json on each deploy. GitHub Actions, Vercel hooks, and GitLab CI all support this.
Add RSS or Atom feed
Agents and monitoring tools can subscribe to change notifications. A simple RSS feed of your changelog entries lets agents stay aware without polling.
Frequently Asked Questions
What does AgentHermes check for in D8 Reliability?
D8 Reliability (weighted 0.13 in the scoring formula) checks response time, uptime indicators, status page availability, HTTP/2 support, and changelog or release notes. The changelog check looks for /changelog, /api/changelog, /docs/changelog, and common variations. It also checks for structured data within those pages — dates, version numbers, and categorized entries score higher than unstructured blog posts.
Does a blog post count as a changelog?
Partially. A blog post titled "Product Update" with a date is better than nothing, but it scores significantly lower than a structured changelog. Agents cannot reliably parse marketing-style prose to determine if an API endpoint changed. A dedicated /changelog page with dated entries, version numbers, and breaking change labels scores highest. A JSON endpoint at /api/changelog scores even higher.
Why do agents care about changelogs?
When an agent makes an API call and gets a 500 error, it needs to decide: retry, adapt, or report failure. Without a changelog, the agent has no way to know if the error is temporary (server issue), permanent (breaking change), or expected (deprecated endpoint). A changelog with affected_endpoints and breaking change labels lets the agent diagnose the issue and adapt automatically — or warn the user that a migration is needed.
How often should a changelog be updated?
Every time a public-facing API changes. For most businesses this means every deployment that affects API behavior, webhook formats, or authentication flows. The best practice is to update the changelog as part of the deployment process — automated, not manual. Companies that automate changelog generation from git commits and deploy metadata have the most reliable changelogs.
What is the difference between a changelog and API versioning?
API versioning (v1, v2, etc.) tells agents which version to call. A changelog tells agents what changed between versions and whether their current integration will break. Both are important. We cover versioning in depth in our API versioning guide. The changelog is the communication layer on top of versioning — it answers "what changed" and "what do I need to do about it."
Does your business have a changelog?
Run your domain through the AgentHermes scanner. D8 Reliability checks for changelogs, status pages, response times, and more. See exactly where you stand.