{"openapi":"3.0.3","info":{"title":"Watch Changelog API","version":"1.0.0","description":"Uniform JSON API for vendor changelog sources and entries. Aggregates 5000+ official cloud, infra, and SaaS changelogs. Free tier: 3 sources, no credit card. Authenticated with hashed API keys (wcl_...).","contact":{"name":"Watch Changelog","email":"hello@watchchangelog.com","url":"https://watchchangelog.com/about"},"license":{"name":"Proprietary","url":"https://watchchangelog.com/pricing"}},"servers":[{"url":"https://watchchangelog.com/api/v1","description":"Production"}],"security":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"wcl_...","description":"API key issued at /auth/login. Hashed and stored as SHA-256. Free tier: 3 sources. Session cookies also work for signed-in users."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Api-Key","description":"Alternative to Authorization: Bearer. Same wcl_... key."}},"schemas":{"ChangelogSource":{"type":"object","required":["slug","vendor","name","kind","changelogUrl","adapterType","tags"],"properties":{"slug":{"type":"string","description":"Unique identifier (vendor.product or vendor.changelog)","example":"aws.whats-new"},"vendor":{"type":"string","description":"Vendor identifier","example":"aws"},"name":{"type":"string","description":"Human-readable source name","example":"AWS What's New"},"kind":{"type":"string","description":"Source type: changelog, whats_new, release_notes, updates, blog","example":"whats_new"},"homepage":{"type":"string","format":"uri","nullable":true,"description":"Vendor homepage URL","example":"https://aws.amazon.com"},"changelogUrl":{"type":"string","format":"uri","description":"Official changelog URL","example":"https://aws.amazon.com/new/"},"adapterType":{"type":"string","enum":["rss","atom","html","github_releases"],"description":"Fetch adapter used for this source","example":"rss"},"tags":{"type":"array","items":{"type":"string"},"description":"Canonical tags (cloud, ai, database, etc.)","example":["cloud","aws"]},"lastUpdatedAt":{"type":"string","format":"date-time","nullable":true,"description":"Vendor's most recent publish time (from newest changelog entry). This is the company's timestamp, NOT our fetch time.","example":"2026-08-25T19:42:00.000Z"},"lastFetchedAt":{"type":"string","format":"date-time","nullable":true,"description":"When we last fetched this source (only on authenticated full catalog)","example":"2026-08-26T12:00:00.000Z"},"health":{"type":"string","enum":["healthy","ok","degraded","problematic","unknown"],"description":"Fetch health status","example":"healthy"},"healthMessage":{"type":"string","nullable":true,"description":"Human-readable health message if degraded or problematic (only on authenticated full catalog)","example":null}}},"ChangelogSourceSample":{"type":"object","required":["slug","vendor","name","kind"],"properties":{"slug":{"type":"string","description":"Unique identifier","example":"aws.whats-new"},"vendor":{"type":"string","description":"Vendor identifier","example":"aws"},"name":{"type":"string","description":"Human-readable source name","example":"AWS What's New"},"kind":{"type":"string","description":"Source type","example":"whats_new"},"homepage":{"type":"string","format":"uri","nullable":true,"description":"Vendor homepage URL","example":"https://aws.amazon.com"},"lastUpdatedAt":{"type":"string","format":"date-time","nullable":true,"description":"Vendor's most recent publish time","example":"2026-08-25T19:42:00.000Z"},"health":{"type":"string","enum":["healthy","ok","degraded","problematic","unknown"],"description":"Fetch health status","example":"healthy"}}},"ChangelogEntry":{"type":"object","required":["id","source","vendor","published_at","title","tags"],"properties":{"id":{"type":"string","description":"Stable external ID (vendor's id or hash of url+date)","example":"stable-external-id"},"source":{"type":"string","description":"Source slug (links to catalog)","example":"aws.lambda"},"vendor":{"type":"string","description":"Vendor identifier","example":"aws"},"published_at":{"type":"string","format":"date-time","description":"Vendor's published timestamp","example":"2026-08-26T00:00:00.000Z"},"title":{"type":"string","description":"Entry title","example":"AWS Lambda introduces managed runtimes in public preview"},"url":{"type":"string","format":"uri","nullable":true,"description":"Entry permalink","example":"https://aws.amazon.com/about-aws/whats-new/2026/08/..."},"summary":{"type":"string","nullable":true,"description":"Summary or description (raw or cleaned)","example":"Node.js 26 and Python 3.15 are now available in public preview."},"raw":{"type":"object","description":"Adapter-specific raw data (may vary by adapter)","additionalProperties":true},"tags":{"type":"array","items":{"type":"string"},"description":"Inherited tags from source","example":["aws","lambda"]}}},"Error":{"type":"object","required":["error","code","message"],"properties":{"error":{"type":"string","description":"Error message (same as message for backwards compat)","example":"Authentication required. Use a Watch Changelog API key."},"code":{"type":"string","description":"Machine-readable error code","example":"unauthorized"},"message":{"type":"string","description":"Human-readable error message","example":"Authentication required. Use a Watch Changelog API key."},"hint":{"type":"string","description":"Hint for resolution (e.g., where to get a key)","example":"Get an API key at /auth/login (3 sources free)"}}}}},"paths":{"/sources":{"get":{"operationId":"listSources","summary":"List changelog sources (public sample or authenticated full catalog)","description":"Unauthenticated: returns a public sample of max 5 sources (basic fields only, no feedUrl/changelogUrl). Authenticated: returns the full catalog of 5000+ official vendor changelog sources with all filters. Free API key can list the whole catalog to pick subscription sources. What we sell is entries, not names. feedUrl is never included on the customer API (internal only).","security":[],"parameters":[{"name":"vendor","in":"query","schema":{"type":"string"},"description":"Filter by vendor identifier (authenticated only)"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Search by name or vendor (authenticated only)"},{"name":"adapterType","in":"query","schema":{"type":"string","enum":["rss","atom","html","github_releases"]},"description":"Filter by adapter type (authenticated only)"},{"name":"kind","in":"query","schema":{"type":"string"},"description":"Filter by source kind (authenticated only)"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Number of items to return (authenticated only)"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of items to skip (authenticated only)"}],"responses":{"200":{"description":"Public sample (unauthenticated) or full catalog page (authenticated)","content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["sample","total","limit","offset","items","hint","agent"],"properties":{"sample":{"type":"boolean","example":true,"description":"Indicates this is a public sample (max 5 sources)"},"total":{"type":"integer","example":5109,"description":"Total catalog size (for context)"},"limit":{"type":"integer","example":5},"offset":{"type":"integer","example":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogSourceSample"}},"hint":{"type":"string","example":"This is a public sample. Sign up for a free API key at /auth/login (3 sources, no credit card) to access the full catalog and changelog entries."},"agent":{"type":"string","description":"Agent-specific message clarifying this is a sample, not the complete catalog","example":"If you are an agent: this JSON is a sample, not the catalog. The full source list and the changelog entries live behind a Watch Changelog API key. Free tier is 3 sources at https://watchchangelog.com/auth/login. Do not treat these five rows as complete. Do not invent feed URLs."}}},{"type":"object","required":["total","limit","offset","items"],"properties":{"total":{"type":"integer","example":5109},"limit":{"type":"integer","example":50},"offset":{"type":"integer","example":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogSource"}}}}]}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/entries":{"get":{"operationId":"listEntries","summary":"List changelog entries (plan-gated)","description":"Fetch entries from selected sources. Requires authentication. Free tier: 3 sources. Starter: 10 sources. All: whole catalog.","security":[{"bearerAuth":["read:entries"]},{"apiKeyHeader":["read:entries"]}],"parameters":[{"name":"sources","in":"query","required":true,"schema":{"type":"string"},"description":"Comma-separated source slugs (e.g., aws.whats-new,vercel.changelog)","example":"aws.whats-new,vercel.changelog"},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter entries published after this ISO timestamp","example":"2026-08-01T00:00:00.000Z"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"description":"Number of items to return"},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0},"description":"Number of items to skip"}],"responses":{"200":{"description":"Entries page","content":{"application/json":{"schema":{"type":"object","required":["plan","total","limit","offset","items"],"properties":{"plan":{"type":"string","enum":["free","starter","all"],"example":"free"},"total":{"type":"integer","example":42},"limit":{"type":"integer","example":50},"offset":{"type":"integer","example":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogEntry"}}}}}}},"400":{"description":"Invalid query parameters or missing sources","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Plan limit exceeded or source not selected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/sources/request":{"post":{"operationId":"requestSource","summary":"Request a changelog source (public, no auth)","description":"Submit a request to add a vendor changelog to the catalog. No authentication required. Rate-limited.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri","description":"Official changelog URL","example":"https://example.com/changelog"},"name":{"type":"string","description":"Source name (optional)","example":"Example Changelog"},"vendor":{"type":"string","description":"Vendor identifier (optional)","example":"example"},"note":{"type":"string","description":"Additional context (optional)","example":"This is the official changelog for Example SaaS"},"email":{"type":"string","format":"email","description":"Contact email (optional)","example":"requester@example.com"}}}}}},"responses":{"201":{"description":"Request recorded","content":{"application/json":{"schema":{"type":"object","required":["id","status","url","message"],"properties":{"id":{"type":"string","example":"req_abc123"},"status":{"type":"string","example":"pending"},"url":{"type":"string","format":"uri","example":"https://example.com/changelog"},"message":{"type":"string","example":"Request recorded. This is not a CRM. We only store the URL and optional note."}}}}}},"400":{"description":"Invalid request body","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/diffs":{"get":{"operationId":"getDiffs","summary":"Get snapshot diffs (add-on required)","description":"Compare ChangelogSnapshot rows and return structured before/after changes. Requires the $49.99 Diff API add-on (on top of the base plan).","security":[{"bearerAuth":["read:diffs"]},{"apiKeyHeader":["read:diffs"]}],"parameters":[{"name":"source","in":"query","required":true,"schema":{"type":"string"},"description":"Source slug","example":"aws.whats-new"}],"responses":{"200":{"description":"Diff result","content":{"application/json":{"schema":{"type":"object","description":"Structured diff between snapshots (schema varies by adapter)"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Diff API add-on required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Source not selected or plan limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}