{"slug": "api-delta-manifest-structured-api-changelog-for-ai-agents-and-devs", "title": "API Delta Manifest: Structured API Changelog for AI Agents and Devs", "summary": "API Delta Manifest (ADM) v1 defines a structured JSON format for API providers to publish machine-readable changelogs, enabling AI coding agents and developers to parse, filter, and act on API changes without guessing. The spec, hosted at a fixed .well-known path, includes fields for severity, endpoints, SDK packages, and codemod URLs, with a JSON Schema for validation. This addresses the problem of teams discovering breaking API changes only at runtime, and supports agents like Claude Code and Devin in automating code updates.", "body_md": "**A machine-readable feed of API changes, built for both AI agents and humans so they can act on them easily**\n\nEvery backend team eventually depends on APIs it doesn't control. When a provider changes something, that information usually arrives as a paragraph in a changelog, a blog post, or an email that gets filtered into a folder no one opens. Nothing in that format tells a computer *which* endpoint changed, *how severe* the change is, or *what code needs to move*. So teams find out at runtime, when a request starts failing in production.\n\nMeanwhile, coding agents (Claude Code, Devin, Cursor, GitHub Copilot workspace agents, and similar tools) are now routinely trusted to read a codebase and open a pull request. That capability is underused here, because there's nothing structured for an agent to read on the provider side. Changelog text is written for humans skimming a page, not for a script deciding whether to touch `payment-service/src/charges.ts`\n\n.\n\n**API Delta Manifest (ADM)** closes that gap. It defines a small, strict JSON format that API providers publish alongside their existing changelog, describing every change in a shape that a script — or an agent — can parse, filter, and act on without guessing.\n\nThis repository defines **v1 of the ADM spec**, scoped intentionally to one piece: **the manifest file itself.** Codemod delivery, webhooks, and consumer-side tooling are natural next steps but are out of scope for v1 so the core format can stabilize first.\n\n**Deterministic, not descriptive.** A field like`severity`\n\nmust be one of a fixed set of values. No agent should have to infer meaning from freeform prose to decide whether a change is safe to ignore.**Diffable.** Each entry is addressable by a stable`id`\n\n, so consumers can track \"which changes have I already applied\" the same way they track applied database migrations.**Additive to what providers already do.** ADM does not replace a human-facing changelog page. It sits next to it as a structured export of the same information.**Small enough to hand-write, strict enough to validate.** A JSON Schema ships with this spec so a manifest can be checked in CI before publishing.\n\nProviders publish the manifest at a fixed, discoverable path:\n\n```\nhttps://api.example.com/.well-known/api-delta-manifest.json\n```\n\nThis follows the existing `.well-known`\n\nconvention (the same one used by `security.txt`\n\nand OAuth discovery documents), so consumers and agents don't need provider-specific configuration to find it — they can always check the same relative path.\n\n```\n{\n  \"adm_version\": \"1.0\",\n  \"provider\": \"acme-payments\",\n  \"generated_at\": \"2026-09-01T12:00:00Z\",\n  \"latest_snapshot\": \"2026-08-28\",\n  \"entries\": [\n    {\n      \"id\": \"acme-2026-08-28-001\",\n      \"released_at\": \"2026-08-28\",\n      \"severity\": \"breaking\",\n      \"kind\": \"field_rename\",\n      \"title\": \"charges.source renamed to charges.payment_method\",\n      \"description\": \"The `source` field on the Charge object is renamed to `payment_method`. The old field remains readable but not writable until the sunset date.\",\n      \"surface\": {\n        \"endpoints\": [\"POST /v1/charges\", \"GET /v1/charges/{id}\"],\n        \"fields\": [\"charges.source\"],\n        \"sdk_packages\": [\n          { \"ecosystem\": \"npm\", \"name\": \"@acme/payments-node\", \"min_safe_version\": \"6.2.0\" },\n          { \"ecosystem\": \"composer\", \"name\": \"acme/payments-php\", \"min_safe_version\": \"4.0.0\" }\n        ]\n      },\n      \"action\": {\n        \"required\": true,\n        \"auto_fixable\": true,\n        \"guidance\": \"Replace reads and writes of `source` with `payment_method`. No value transformation needed.\",\n        \"codemod_url\": \"https://cdn.acme.com/adm/codemods/acme-2026-08-28-001.js\",\n        \"docs_url\": \"https://docs.acme.com/changes/acme-2026-08-28-001\"\n      },\n      \"sunset_at\": \"2027-02-28\",\n      \"supersedes\": null\n    }\n  ]\n}\n```\n\n| Field | Type | Required | Notes |\n|---|---|---|---|\n`adm_version` |\nstring | yes | Spec version this document conforms to, e.g. `\"1.0\"` . |\n`provider` |\nstring | yes | Short, stable, lowercase-hyphenated identifier for the API. Should not change once published. |\n`generated_at` |\nstring (ISO 8601) | yes | Timestamp the file was generated. Consumers can use this to detect staleness. |\n`latest_snapshot` |\nstring (ISO 8601 date) | yes | The date-based version identifier of the newest API revision described here. |\n`entries` |\narray of Entry objects | yes | One object per change. Newest first. Never delete or mutate a past entry; append instead. |\n\n| Field | Type | Required | Notes |\n|---|---|---|---|\n`id` |\nstring | yes | Globally unique, stable, never reused. Recommended pattern: `{provider}-{date}-{sequence}` . |\n`released_at` |\nstring (ISO 8601 date) | yes | When the change went live. |\n`severity` |\nenum | yes | One of: `breaking` , `deprecation` , `additive` , `patch` . See table below. |\n`kind` |\nenum | yes | One of: `field_rename` , `field_removal` , `field_addition` , `endpoint_removal` , `endpoint_addition` , `behavior_change` , `auth_change` , `rate_limit_change` , `other` . |\n`title` |\nstring | yes | One line, plain text, no markdown. Should be understandable without reading `description` . |\n`description` |\nstring | yes | Plain-language explanation. Markdown allowed. This is the only field meant primarily for a human reader; agents should rely on the structured fields, not parse this one. |\n`surface` |\nobject | yes | See below. Describes exactly what changed. |\n`action` |\nobject | yes | See below. Describes what a consumer (or their agent) should do about it. |\n`sunset_at` |\nstring (ISO 8601 date) or `null` |\nno | Date after which the old behavior stops working. Omit or `null` if there is no deadline (e.g. purely additive changes). |\n`supersedes` |\nstring or `null` |\nno | The `id` of an earlier entry this one revises or corrects, if any. |\n\n| Field | Type | Required | Notes |\n|---|---|---|---|\n`endpoints` |\narray of strings | no | Each formatted as `\"{METHOD} {path}\"` , e.g. `\"POST /v1/charges\"` . Use the path template with parameter placeholders (e.g. `{id}` ), not a resolved URL. Supports `ANY` in place of a method — see below. |\n`fields` |\narray of strings | no | Dot-notated, e.g. `\"charges.source\"` . |\n`sdk_packages` |\narray of objects | no | Each has `ecosystem` (`npm` , `composer` , `pip` , `gem` , `go` , etc.), `name` , and `min_safe_version` — the first package version where this change is already reflected. |\n\nAt least one of `endpoints`\n\n, `fields`\n\n, or `sdk_packages`\n\nmust be present — an entry with an empty `surface`\n\ngives a consumer nothing to match against and should not validate.\n\n`endpoints`\n\nentries are `\"{METHOD} {path}\"`\n\nstrings:\n\n**Path templates** use parameterized placeholders like`{id}`\n\nor`{customer_id}`\n\nfor variable segments (e.g.`\"GET /v1/customers/{id}/invoices\"`\n\nor`\"POST /v1/charges\"`\n\n). Wildcards (like`*`\n\n) are not used in paths — route paths should be explicitly defined with parameter placeholders to ensure precise and deterministic matching.matches every HTTP method on that path. Use this when a change affects a route regardless of verb — for example, an auth change that applies to`ANY`\n\nas the method`GET`\n\n,`POST`\n\n, and`DELETE`\n\non the same resource alike:\n\n```\n\"ANY /v1/charges/{id}\"\n```\n\nIf a change affects multiple endpoints across an API, list each specific endpoint template instead of using broad patterns. Consumers and AI agents rely on explicit route definitions in `surface`\n\nto target code patches accurately without having to guess.\n\n| Field | Type | Required | Notes |\n|---|---|---|---|\n`required` |\nboolean | yes | Whether a consumer must change anything to remain compatible. `false` for purely additive changes. |\n`auto_fixable` |\nboolean | yes | Whether a mechanical code transform can resolve this without human judgment. |\n`guidance` |\nstring | yes | Plain-language instruction for what to change. Written so an agent can act on it even without `codemod_url` . |\n`codemod_url` |\nstring (URL) or `null` |\nno | Link to a runnable transform (e.g. a jscodeshift script, a Rector rule, an ast-grep pattern). Present only when `auto_fixable` is `true` . |\n`docs_url` |\nstring (URL) or `null` |\nno | Link to full human-readable documentation of the change. |\n\n| Value | Meaning |\n|---|---|\n`breaking` |\nExisting integrations will fail or misbehave unless updated. |\n`deprecation` |\nCurrent behavior still works but is scheduled for removal by `sunset_at` . |\n`additive` |\nNew capability. Nothing existing is affected. |\n`patch` |\nBug fix or clarification with no expected impact on correctly-written integrations. |\n\n[ examples/acme-payments.api-delta-manifest.json](/hassan-jahan/api-delta-manifest/blob/main/examples/acme-payments.api-delta-manifest.json) is a complete, valid manifest for a fictional payments API. It deliberately covers all four severities and shows the\n\n`ANY`\n\nmethod and parameterized path templates in use (`acme-2026-08-10-004`\n\nand `acme-2026-08-28-001`\n\n), so it can double as a reference when writing or generating a manifest of your own.A [JSON Schema](/hassan-jahan/api-delta-manifest/blob/main/schema/adm-v1.schema.json) is provided in this repo. Providers should validate every manifest against it before publishing, ideally as a CI step that fails the build on an invalid document.\n\n```\nnpm install\nnpm run validate\n```\n\nThis runs [ajv-cli](https://github.com/ajv-validator/ajv-cli) against every file in `examples/`\n\nusing `schema/adm-v1.schema.json`\n\n. Point it at your own manifest with:\n\n```\nnpx ajv validate -s schema/adm-v1.schema.json -d path/to/your-manifest.json --strict=true\n```\n\nIf you are an agent tasked with producing an ADM file on behalf of an API provider:\n\n**One entry per discrete change.** Do not bundle multiple unrelated field changes into a single entry — a consumer filtering by`surface.fields`\n\nneeds each change isolated.**Never omit** If a change doesn't cleanly fit an existing`severity`\n\nor`kind`\n\n, and never invent values outside the enums above.`kind`\n\n, use`\"other\"`\n\nand explain fully in`description`\n\n— do not create a new enum value.Once a manifest is published, treat every existing`id`\n\nmust be stable and unique before you finalize the entry.`id`\n\nas immutable. Re-publishing must append new entries, never rewrite old ones.**Only set** If no transform exists yet, set it to`action.auto_fixable: true`\n\nif`action.codemod_url`\n\nactually resolves to a working transform.`false`\n\nand rely on`action.guidance`\n\nalone.**Write** Prefer \"Replace`action.guidance`\n\nas an instruction, not a description.`X`\n\nwith`Y`\n\n\" over \"The`X`\n\nfield was renamed to`Y`\n\n\" — the former is directly actionable, the latter requires re-interpretation.**If you are consuming a manifest to patch a codebase**, filter entries by`severity`\n\nand`surface`\n\nbefore reading`description`\n\n, cross-reference`surface.sdk_packages[].min_safe_version`\n\nagainst the consumer's installed version to skip changes already absorbed by a dependency bump, and only fall back to interpreting`description`\n\nin free text when`action.codemod_url`\n\nis absent and`action.guidance`\n\nis insufficient to write a mechanical patch.**Prefer specific HTTP methods over** Listing specific methods and route templates gives downstream consumers precision they rely on to avoid unnecessary inspection.`ANY`\n\nunless the change truly is method-agnostic.\n\nThis version defines only the manifest format and its hosting location. Deliberately excluded for now, to keep the core spec stable and reviewable:\n\n- A push/webhook delivery mechanism for new entries\n- A required format for\n`codemod_url`\n\npayloads (jscodeshift vs. Rector vs. ast-grep are all currently allowed; a follow-up spec may standardize this) - A consumer-side lockfile format for tracking which entries have already been applied\n\nProposals for any of the above are welcome as issues in this repo.\n\nThis is a draft specification. See [CONTRIBUTING.md](/hassan-jahan/api-delta-manifest/blob/main/CONTRIBUTING.md) for how to propose a change. In short: open an issue describing the problem before proposing a fix, and back up any change to `schema/adm-v1.schema.json`\n\nwith a concrete example under `examples/`\n\nthat demonstrates it. Backwards-incompatible changes to the spec itself bump `adm_version`\n\n, following the same discipline the spec asks of API providers — see [CHANGELOG.md](/hassan-jahan/api-delta-manifest/blob/main/CHANGELOG.md) for how that's tracked here.\n\nMIT License.", "url": "https://wpnews.pro/news/api-delta-manifest-structured-api-changelog-for-ai-agents-and-devs", "canonical_source": "https://github.com/hassan-jahan/api-delta-manifest", "published_at": "2026-09-01 18:52:03+00:00", "updated_at": "2026-09-01 19:23:37.714315+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents"], "entities": ["API Delta Manifest", "Claude Code", "Devin", "Cursor", "GitHub Copilot"], "alternates": {"html": "https://wpnews.pro/news/api-delta-manifest-structured-api-changelog-for-ai-agents-and-devs", "markdown": "https://wpnews.pro/news/api-delta-manifest-structured-api-changelog-for-ai-agents-and-devs.md", "text": "https://wpnews.pro/news/api-delta-manifest-structured-api-changelog-for-ai-agents-and-devs.txt", "jsonld": "https://wpnews.pro/news/api-delta-manifest-structured-api-changelog-for-ai-agents-and-devs.jsonld"}}