# Havoptic API

> Typed, evidence-backed release intelligence for AI coding tools (Claude Code, OpenAI Codex CLI, Cursor, Gemini CLI, Kiro CLI, GitHub Copilot CLI, Devin Desktop, Antigravity CLI, Grok Build). Read-only, no key needed, JSON by default. Base URL: https://api.havoptic.com/v1 (same data at https://www.havoptic.com/api/v1).

## Start here
- GET /v1/changes?tool=claude-code&kind=breaking,security&since=30d — typed change items, newest first
- GET /v1/tools/{tool}/upgrade?from=2.1.290 — breaking changes, deprecations, security fixes and features between two versions (Accept: text/markdown for a ready-to-read brief)
- GET /v1/digest?since=7d — what changed across tools this week, breaking first (Accept: text/markdown)
- GET /v1/tools/{tool}/latest — latest stable release
- GET /v1/releases?tool={tool}&limit=20 — releases, cursor-paginated (next_cursor → ?cursor=)
- GET /v1/releases/{id}?expand=changes — one release (ids: claude-code-2.1.302 or claude-code@2.1.302)
- GET /v1/search?q=mcp+oauth — search change items and release notes
- GET /v1/tools/{tool} — product metadata, latest stable/prerelease, cadence, source health; /v1/tools/{tool}/versions/{version} resolves one version (latest, v-prefix, rust-v ok)
- GET /v1/compare?tools=claude-code,cursor,openai-codex&aspects=cadence,features,recent_changes,verdict — compare 2–4 tools
- GET /v1/features, /v1/features/{id} — feature ids, first-to-ship adoption and per-tool support; /v1/trends/cadence?window=30d, /v1/trends/feature-adoption, /v1/trends/mechanics
- GET /v1/status — data freshness per source; GET /v1/changelog — API changes

## What the fields mean
- changes[]: { id, kind, title, evidence, confidence }. kind is one of feature, fix, breaking, deprecation, security, improvement, removal, performance, model, pricing, policy. evidence is a verbatim quote from the vendor's notes — cite it.
- changes_available: false means the release predates typed extraction (2026-10-19); read its summary/notes instead and do not assume it had no breaking changes.
- abstract: neutral one-line summary. summary: marketing copy (do not cite as fact).
- has_breaking / has_security: true, false, or null (unknown for legacy releases).

## Conventions
- Errors are RFC 9457 application/problem+json; invalid filter values return 400 naming the parameter.
- ETag/If-None-Match → 304. Responses are cached ~5 min; please cache too.
- fields=id,version,abstract trims list items; Accept: text/markdown on digest/upgrade/changelog.
- Header Havoptic-Version is the API version date. Schemas: GET /v1/schemas/{release|change|...}.json; OpenAPI: https://www.havoptic.com/openapi.json

## Other surfaces
- MCP (streamable HTTP): https://mcp.havoptic.com/mcp — tools whats_changed_since, get_upgrade_notes, get_breaking_changes, search_changes, get_release, …
- Feeds: https://www.havoptic.com/feeds/changes.xml?kind=breaking (RSS/Atom/JSON)
- Bulk: GET /v1/export/manifest.json lists releases.{json,ndjson,csv,parquet}, changes.ndjson and daily deltas/{YYYY-MM-DD}.ndjson (CC BY 4.0, attribute "Havoptic")
- Docs: https://www.havoptic.com/docs (keys and limits, webhooks, MCP); every error type resolves at https://www.havoptic.com/docs/errors/{type}