Example

{ "openapi": "3.0.0", "info": { "title": "RSS/Atom Feed Validator API: RSS 2.0, Atom and JSON Feed Checker", "description": "One GET, one graded JSON report: a headless RSS/Atom/JSON Feed validator for CI checks, publishing pipelines and feed directories. Give it a feed URL (or a website that links to its feed) and get a JSON report: the detected format, basic XML well-formedness checks (unclosed or mismatched tags, bare ampersands, undefined entities), required and recommended elements, date formats, duplicate IDs, enclosure attributes and basic podcast fields, plus a grade (A+ to F) and a score out of 100. Not affiliated with the W3C or any feed reader.\n\nFormats: RSS 2.0 (and older 0.9x), Atom 1.0 (RFC 4287), RSS 1.0 (RDF, light checks) and JSON Feed 1 / 1.1. /v1/check GETs the URL (up to 5 redirects, first 1 MB). If the URL is an HTML page it follows the first feed it advertises and reports up to 4 others under discoveredFrom. /v1/validate checks feed text you send in (XML or JSON Feed), offline with no outbound request.\n\nChecks include: bare ampersands and mismatched tags (with line numbers), missing channel title/link/description (RSS) or id/title/updated and author (Atom), RFC 822 and RFC 3339 dates, duplicate guid/id values, items without title or description, relative links, enclosures without url/length/type, atom:link rel=self, language codes, and for podcasts (itunes namespace plus enclosures) the image, category and explicit tags. Issue codes are stable snake_case strings (for example unescaped_ampersand, xml_not_well_formed, duplicate_guid, enclosure_length_missing, invalid_rfc822_date, invalid_rfc3339_date); severity is error, warning or info. One error scores 75 (grade C), so gate on summary.errors rather than on the grade alone.\n\nLimits: the rule set and the XML parser are our own, so results can differ from other validators and do not guarantee acceptance by any podcast directory or feed reader (podcast image sizes are not measured); the XML parser and ignores DTD entities (no entity expansion); documents are limited to 1 MB (larger feeds return grade unchecked), 10 seconds in total, non-UTF-8 feeds are decoded as UTF-8, 60,000 elements and 64 levels of nesting; at most 200 issues are returned. Only the feed document is read - linked pages, images and audio files are not requested. A malformed feed (not well-formed XML) is capped at a score of 40. If a site answers HTTP 4xx/5xx or the feed is too large the grade is unchecked; a URL that is not a feed returns grade not_a_feed; unchecked and not_a_feed are not passes. /v1/check results are cached for 6 hours per URL; add fresh=1 to bypass the cache. Private-network targets are rejected.", "version": "1.0.0", "x-category": "Data" }, "servers": [ { "url": "https://feed-validator.glowhalo.org" } ], "paths": { "/v1/check": { "get": { "summary": "Validate the RSS/Atom feed at a URL", "description": "GETs the URL (up to 5 redirects, first 1 MB). A page that advertises a feed is followed to that feed. Cached 6 hours; pass fresh=1 to bypass. A scheme-less value such as example.com/feed is treated as https.", "operationId": "checkFeed", "parameters": [ { "name": "url", "in": "query", "required": true, "description": "Feed URL or a web page that links to its feed. Aliases u, uri, link, target, site, website, domain and host are also accepted (case-insensitive).", "schema": { "type": "string" }, "example": "https://hnrss.org/frontpage" }, { "name": "fresh", "in": "query", "required": false, "description": "Set to 1 to bypass the result cache.", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Validation report. found is false and grade is not_a_feed when the URL is not a feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grade": { "type": "string", "description": "A+ to F derived from score (A+ 97+, A 90+, B 80+, C 70+, D 60+, F below). not_a_feed: the URL is not an RSS/Atom/JSON feed. unchecked: HTTP 4xx/5xx or a feed larger than 1 MB." }, "score": { "type": "number", "nullable": true, "description": "100 minus 25 per error and 10 per warning, minus 1 per info up to 5 in total (minimum 0)." }, "summary": { "type": "object", "properties": { "errors": { "type": "integer" }, "warnings": { "type": "integer" }, "infos": { "type": "integer" } } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "cached": { "type": "boolean" }, "checkedAt": { "type": "string" }, "note": { "type": "string" }, "url": { "type": "string" }, "finalUrl": { "type": "string" }, "statusCode": { "type": "integer" }, "contentType": { "type": "string" }, "found": { "type": "boolean", "nullable": true }, "format": { "type": "string", "nullable": true, "description": "rss2.0, atom1.0, rss1.0, jsonfeed1 or jsonfeed1.1.", "example": "rss2.0" }, "discoveredFrom": { "type": "object", "nullable": true, "description": "Set when the URL was a web page; shows which advertised feed was validated.", "properties": { "pageUrl": { "type": "string" }, "feedsFound": { "type": "integer" }, "used": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "string" } } } }, "feed": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "description": { "type": "string" }, "language": { "type": "string" }, "updated": { "type": "string" }, "itemCount": { "type": "integer" } } } } } } } }, "400": { "description": "Bad input: missing_url, invalid_url, credentials_in_url, unsupported_protocol, forbidden_host (private network), url_too_long.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "usage": { "type": "string" }, "example": {} } } } } }, "502": { "description": "The target could not be fetched (fetch_failed, resolve_failed).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "usage": { "type": "string" }, "example": {} } } } } }, "504": { "description": "The target did not answer within 10 seconds (timeout).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "usage": { "type": "string" }, "example": {} } } } } } } } }, "/v1/validate": { "post": { "summary": "Validate feed text you send in", "description": "Offline validation, no outbound request. Send the feed as XML text, JSON Feed text or a JSON Feed object in the feed field. Maximum 1 MB.", "operationId": "validateFeed", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "feed" ], "properties": { "feed": { "description": "Feed as a string (RSS/Atom XML or JSON Feed text) or as a JSON Feed object.", "example": "Examplehttps://example.comExample feedHellohttps://example.com/hellohttps://example.com/hello" } } }, "example": { "feed": "Examplehttps://example.comExample feedHellohttps://example.com/hellohttps://example.com/hello" } } } }, "responses": { "200": { "description": "Validation report for the supplied feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "grade": { "type": "string", "description": "A+ to F derived from score (A+ 97+, A 90+, B 80+, C 70+, D 60+, F below). not_a_feed: the URL is not an RSS/Atom/JSON feed. unchecked: HTTP 4xx/5xx or a feed larger than 1 MB." }, "score": { "type": "number", "nullable": true, "description": "100 minus 25 per error and 10 per warning, minus 1 per info up to 5 in total (minimum 0)." }, "summary": { "type": "object", "properties": { "errors": { "type": "integer" }, "warnings": { "type": "integer" }, "infos": { "type": "integer" } } }, "issues": { "type": "array", "items": { "type": "object", "properties": { "severity": { "type": "string", "enum": [ "error", "warning", "info" ] }, "code": { "type": "string" }, "message": { "type": "string" } } } }, "cached": { "type": "boolean" }, "checkedAt": { "type": "string" }, "note": { "type": "string" }, "url": { "type": "string" }, "finalUrl": { "type": "string" }, "statusCode": { "type": "integer" }, "contentType": { "type": "string" }, "found": { "type": "boolean", "nullable": true }, "format": { "type": "string", "nullable": true, "description": "rss2.0, atom1.0, rss1.0, jsonfeed1 or jsonfeed1.1.", "example": "rss2.0" }, "discoveredFrom": { "type": "object", "nullable": true, "description": "Set when the URL was a web page; shows which advertised feed was validated.", "properties": { "pageUrl": { "type": "string" }, "feedsFound": { "type": "integer" }, "used": { "type": "string" }, "alternatives": { "type": "array", "items": { "type": "string" } } } }, "feed": { "type": "object", "properties": { "title": { "type": "string" }, "link": { "type": "string" }, "description": { "type": "string" }, "language": { "type": "string" }, "updated": { "type": "string" }, "itemCount": { "type": "integer" } } } } } } } }, "400": { "description": "Bad input: invalid_json, invalid_body, missing_feed, invalid_feed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "usage": { "type": "string" }, "example": {} } } } } }, "413": { "description": "payload_too_large: the body exceeds 1 MB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "usage": { "type": "string" }, "example": {} } } } } } } } } } }