For API providers · Open format · MIT
Don't just announce
API changes. Apply them.
Describe a change once, in a signed notice on your own domain. Every customer that follows you gets a pull request that adapts their code, before the old responses stop. No server in between, and none of their code leaves their CI.
Changelogs nobody reads, deprecation emails that land in a shared inbox, and a cutoff date that arrives anyway. Then the tickets start. Your customers' code reads phone the day you ship phone_number, and every one of them fixes it alone.
How it works
One notice.
A pull request each.
A notice is a small JSON file in an open format: the same paths and change kinds Tiltmeter uses for drift, so a customer's agent knows exactly what to follow, without reading prose.
/.well-known/api-change-key on your domain. Only you can speak for your API./.well-known/api-changes.json, a static file any host serves: your docs site, GitHub Pages, a bucket.Write it in a minute.
Review the draft, rewrite the summary in your words, and add a note where the new format matters, such as "a decimal string, like 12.00". The date the old responses stop goes in the pull request title.
$ tiltmeter notice keygen key.pem \ --public site/.well-known/api-change-key $ tiltmeter notice create --from-openapi v2.yaml v3.yaml \ --effective 2026-12-01 -o notice.json ✓ drafted notice 2026-11-03-customers with 4 changes $ tiltmeter notice sign notice.json --key key.pem $ tiltmeter notice publish notice.json \ --feed site/.well-known/api-changes.json ✓ published 2026-11-03-customers
From CI
Every spec change
comes with its notice.
The GitHub Action comments a draft notice on every pull request that changes your spec's responses, and can fail the check until one is added. On merge, it signs the notices with your secret key into the feed and hands the folder to Pages.
# .github/workflows/api-notices.yml - uses: tiltmeter-dev/tiltmeter-action@v1 with: mode: notice-draft # on pull requests spec: openapi.yaml require-notice: true
- uses: tiltmeter-dev/tiltmeter-action@v1 with: mode: notice-publish # on main env: TILTMETER_SIGNING_KEY: ${{ secrets.TILTMETER_SIGNING_KEY }}
Your customers
Two lines on
their side.
They list you under subscriptions and add a scheduled workflow. A plain text search decides first whether a repository uses your hosts, paths, SDKs and the fields that change, so the ones that don't cost nothing and get nothing. The fix runs on their own agent and API key, in a sandboxed worktree, and lands as a pull request they review.
- Before the cutoff. The pull request opens as soon as you publish, dated with
effective_at. - Left for a human. What the agent cannot know, such as a new number format, is listed for the reviewer, with your note quoted.
- No lock-in. The format is open, and anyone can implement a reader.
# tiltmeter.yaml subscriptions: - provider: api.acme.example
# .github/workflows/api-notices.yml, every 6 hours - uses: tiltmeter-dev/tiltmeter-action@v1 with: mode: notices
✓ opened https://github.com/their-org/billing/pull/42 - api.acme.example 2026-11-03-customers not affected
Only you can
speak for your API.
- Signed by your domain. A notice verifies only against the key at
https://<you>/.well-known/api-change-key, and every endpoint in it must be on your domain. - Inert text. Your summary and notes reach agents marked as data, never as instructions, and pull requests as plain text: no links, mentions or HTML.
- Nothing merges itself. Your customers review every pull request like any other change. Their code stays in their CI.
Questions
Before you
publish.
notice create --from-check.