API reference
Model changes: webhooks, feeds and the changes API
Models that join or leave Vani Chat or the Vani API, and models scheduled for retirement, are entries of the public changelog at vani.ai/changelog. Follow it as a feed, poll the changes API, or have each change sent to your server as a signed webhook. If your account used a model in the last 30 days and has an API key in use, you also get a note in your Updates when the model leaves.
- Webhooks
- Up to 5 endpoints per account, signed (Standard Webhooks)
- Feeds
- vani.ai/changelog/rss.xml · /changelog/feed.json
- Polling
- GET /models/changes?since=… (no key)
- Price
- Free
On this pageEvents
Events
Each changelog entry has one event. An entry can name several models, for example two models taken offline together.
- An entry may say which model to use instead (
instead, a model id), and link the docs or an announcement. - Entries are written when a model's listing changes and stays changed for half an hour, or by our team. A short outage that is over in minutes is not an entry.
| Event | When |
|---|---|
model.added | A model is new in Vani Chat or on the Vani API. |
model.restored | A model that was offline is available again. |
model.unavailable | A model is taken offline for now. Requests that name it are refused. |
model.retired | A model is gone for good. Requests that name it are refused. |
model.deprecated | A model will be retired on a date (retires_on). |
model.api_removed | A model leaves the Vani API but stays in Vani Chat. |
api.feature | A new way to use the models on the API. |
Webhooks
Add an endpoint signed in, under Webhooks in the console, and choose its events (all of them by default). Its signing secret (whsec_…) is shown once; you can rotate it there, and send a test event.
- Every entry published after the endpoint was added is sent once, as an HTTPS
POSTwith a JSON body:type(the event),timestamp(when the entry was published) anddata(the entry exactly asGET /changelogshows it). - Each request is signed the Standard Webhooks way, so its libraries verify it:
webhook-id(the same on every retry),webhook-timestamp(Unix seconds) andwebhook-signature(v1,and the base64 HMAC-SHA256 of<webhook-id>.<webhook-timestamp>.<body>, keyed with the bytes of the secret afterwhsec_). Reject a request whose signature does not match or whose timestamp is more than five minutes old. - Answer with any 2xx status within 10 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2, 6 and 12 hours. After 3 events in a row failed every retry, the endpoint is disabled and the console says so; enable it again there.
- The endpoint must be a public
https://address on port 443. Redirects are not followed and the response body is not read. - An entry that is withdrawn before it is sent is not sent. An entry about a change detected automatically is sent about an hour after it is published.
A delivery
POST /your/endpoint HTTP/1.1
Content-Type: application/json
webhook-id: 019a7c3e-5f1d-7a2b-9c4e-2b7d0e6f1a90
webhook-timestamp: 1794470400
webhook-signature: v1,<base64 signature>
{"type": "model.retired", "timestamp": "2026-11-10T06:13:00Z", "data": {"id": "…", "date": "2026-11-10", "kind": "retired", "event": "model.retired", "models": [{"slug": "moonshotai/kimi-k3.1-pro-derisked", "name": "Kimi K3.1 Pro Derisked", "vendor": "Moonshot AI", "instead": "zhipu/glm-5.3-derisked"}], "note": "…", "news": null, "docs": null, "retires_on": null, "published_at": "2026-11-10T06:13:00Z"}}Verify it (Python, standard library)
import base64, hashlib, hmac, time
def verified(headers, body: bytes, secret: str) -> bool:
key = base64.b64decode(secret.removeprefix("whsec_"))
signed = f"{headers['webhook-id']}.{headers['webhook-timestamp']}.".encode() + body
expected = "v1," + base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
fresh = abs(time.time() - int(headers["webhook-timestamp"])) < 300
return fresh and any(hmac.compare_digest(expected, s) for s in headers["webhook-signature"].split(" "))The changes API
GET /models/changes lists the same changes, one row per model, oldest first, without an API key. Pass the next_since of your last call as since to get only what is new.
Poll for changes
curl "https://api.vani.ai/v1/models/changes?since=2026-11-01T00:00:00Z"The answer (shortened)
{
"schema_version": 1,
"changes": [
{"id": "…:moonshotai/kimi-k3.1-pro-derisked", "event": "model.retired", "at": "2026-11-10T06:13:00Z", "date": "2026-11-10",
"model": "moonshotai/kimi-k3.1-pro-derisked", "name": "Kimi K3.1 Pro Derisked", "vendor": "Moonshot AI",
"instead": "zhipu/glm-5.3-derisked", "retires_on": null, "note": "…", "docs": null}
],
"next_since": "2026-11-10T06:13:00Z"
}Note
GET /changelog returns the entries themselves, newest first, as the page shows them. Both answers are cached for a minute.Feeds
- RSS 2.0:
https://vani.ai/changelog/rss.xml. - JSON Feed 1.1:
https://vani.ai/changelog/feed.json. Each item also carries the change itself under_vani(kind, date, models,retires_on). - Both carry the newest 50 entries and are refreshed every few minutes.
More reference: OpenAI-compatible API · Anthropic-compatible API · Model ids, limits, headers and usage · Images and PDFs on the API · MCP tools on the API · Web search and web fetch tools · Media API: images and videos · Artifacts API · Responses API: scope and limits · API overview · Docs and quickstart