# Version Watch Agent Access

Version Watch tracks official developer platform changelogs, release notes, docs updates, RSS feeds, and GitHub releases. Use it as a public change intelligence layer for developer tools and agents.

Version Watch is a Convex-backed snapshot API. It does not scrape vendor sites on each public API request. When freshness matters, check the status endpoint before reporting results as complete.

Base URL: https://versionwatch.dev

## Recommended Endpoints

- Latest updates: https://versionwatch.dev/api/v1/updates
- High-signal updates: https://versionwatch.dev/api/v1/updates?severity=high&limit=25
- Critical updates: https://versionwatch.dev/api/v1/updates?severity=critical&limit=25
- Vendor list: https://versionwatch.dev/api/v1/vendors
- API status: https://versionwatch.dev/api/v1/status
- Vendor freshness: https://versionwatch.dev/api/v1/status/vendors
- Taxonomy: https://versionwatch.dev/api/v1/taxonomy
- OpenAPI contract: https://versionwatch.dev/api/v1/openapi.json
- Markdown feed: https://versionwatch.dev/feed.md
- JSON feed: https://versionwatch.dev/api/v1/feed.json
- API documentation: https://versionwatch.dev/agent-access
- LLM resource map: https://versionwatch.dev/llms.txt
- Version Watch skill: https://versionwatch.dev/skills/version-watch/SKILL.md

## Filters

Use query parameters on /api/v1/updates, /api/v1/feed.json, /api/v1/feed.md, and /feed.md.

- since: ISO 8601 timestamp, for example 2026-04-24T00:00:00Z
- vendor: vendor slug, for example openai, stripe, vercel, github, cloudflare, convex
- severity: critical, high, medium, or low
- audience: frontend, backend, infra, ai, product, security, compliance, or related audience labels
- tag: matches categories or affected stack tags such as api, auth, billing, sdk, agents, hosting, deployments
- limit: defaults to 25 and clamps at 100
- cursor: opaque pagination cursor returned as next_cursor

## Response Fields

Each public update includes:

- id
- vendor
- vendor_slug
- title
- published_at
- severity
- signal_score
- audience
- tags
- summary
- why_it_matters
- recommended_action
- source_url
- github_url
- version_watch_url

List responses also include schema_version, generated_at, status_url, count, total_count, filters, and next_cursor.

The recommended_action field is the most useful field for agents. Treat it as an action hint, then cite source_url or version_watch_url for attribution.

Errors use a stable shape: error.code and error.message. Current public codes are invalid_filter, invalid_cursor, and not_found.

## Freshness Contract

- healthy: the public Convex snapshot refreshed inside the expected window and active sources are clean.
- degraded: the snapshot is recent, but one or more active sources failed, are stale, backed off, or the latest refresh was partial.
- stale: no acceptable refresh completed within the freshness window.

Version Watch uses adaptive source freshness. A 15-minute Convex scheduler fetches only due sources. Critical vendors refresh faster, long-tail sources refresh slower, and failing sources back off before retrying.

Paused and unsupported sources are visible as coverage states but do not count as global freshness debt. Degraded sources are still monitored and should be treated as incomplete coverage until they recover.

For vendor-specific workflows, call /api/v1/status/vendors/{slug} before acting on a single platform.

Agents should mention degraded or stale status when producing release gates, incident reports, migration plans, or other high-confidence operational summaries.

## Pagination

- Treat next_cursor as opaque.
- Pass it back as the cursor query parameter to fetch the next page.
- Do not decode it or build offset assumptions around it.
- Store delivered update ids and de-duplicate by id before posting alerts or creating tasks.

## Use Cases

Agents should use Version Watch to:

- Detect breaking platform changes before upgrades or deployments
- Monitor APIs, SDKs, auth systems, billing systems, hosting providers, and AI platforms used by a project
- Summarize relevant updates for engineering teams
- Alert maintainers when a vendor ships a high-impact change
- Enrich dependency, release, and migration reviews with current vendor context
- Create tasks in Linear, Jira, GitHub Issues, or similar project systems when review is needed
- Post filtered digests into Discord, Slack, Microsoft Teams, Telegram, or internal portals
- Feed internal dashboards, knowledge bases, data warehouses, and weekly engineering reports

## Agent Workflow

1. Determine the project stack or vendor list.
2. Call /api/v1/status when freshness or operational confidence matters.
3. Call /api/v1/vendors if you need valid vendor slugs.
4. Call /api/v1/taxonomy if you need valid severities, audiences, tags, source types, and vendor slugs.
5. Query /api/v1/updates with vendor, severity, audience, tag, since, limit, and cursor filters.
6. Continue pagination while next_cursor is present and more results are needed.
7. De-duplicate updates by id before notifying a user or posting to a channel.
8. Summarize only updates that match the user or project context.
9. Include recommended_action when giving advice.
10. Cite source_url for the official vendor source and version_watch_url for the Version Watch record.

## Integration Guidance

- Discord or Slack: poll filtered updates from a scheduled worker, then post vendor, title, summary, recommended_action, and version_watch_url.
- CI/CD: query high or critical updates before release and flag matching vendor, API, SDK, auth, hosting, infra, or billing changes.
- Agents and IDEs: fetch context before suggesting dependency upgrades, migration plans, or code changes.
- Issue trackers: create review tasks for critical or high updates that match a team's vendors or tags.
- Data platforms: store update id, vendor_slug, severity, published_at, tags, recommended_action, source_url, and version_watch_url.

## Guardrails

- Do not claim to have read the official source unless you actually open source_url.
- Do not notify repeatedly for the same id.
- Prefer filtered queries over broad feeds for notifications.
- For recurring polling, use a 15 to 60 minute interval unless the user asks for a different cadence.
- If /api/v1/status is degraded or stale, include that caveat in summaries and avoid claiming complete coverage.