{ "documentation_version": 1, "base_url": "https://c7dev.com", "instructions_url": "https://c7dev.com/api_instructions", "selection": { "method": "GET", "parameter": "api", "required": false, "description": "Omit api for the full suite, or use an endpoint name for its instructions only.", "example_url": "https://c7dev.com/api_instructions?api=media_api" }, "instructions": [ "Choose an endpoint by its description, then use its documented HTTP method and parameter location.", "URL-encode GET query values. Preserve identifiers such as VAT numbers and registration codes as strings.", "For JSON APIs, require HTTP success and result=true before using returned data. Read error_message on failure.", "Do not fabricate missing data or treat null as zero or false. Warnings may indicate incomplete or older data.", "Do not blindly retry invalid input or access errors. Temporary service failures may be retried with bounded backoff.", "Responses prohibit browser caching. Inspect cached, timestamps and X-API-Version when those fields are available." ], "authentication": { "documentation": "Public; no token is required to read these instructions.", "restricted_endpoints": "Supply credentials provided by the API operator when access control requires them.", "token_locations": [ "Authorization: Bearer YOUR_ACCESS_TOKEN", "X-Access-Token: YOUR_ACCESS_TOKEN", "access_token query or form parameter" ], "domain": "Send domain as a query or form parameter when the client token is restricted to registered domains. Access may also be restricted by IP.", "ai_generate": "Requires both access_token and domain in the form body." }, "json_response_envelope": { "result": "boolean; request succeeded", "error": "boolean; request failed", "error_message": "string; empty on success", "server_time": "integer; Unix timestamp in seconds" }, "errors": { "400": "Missing or invalid input.", "403": "Access denied; check token, registered domain and IP permissions.", "404": "Unknown API selected for instructions.", "405": "Unsupported method for the instructions endpoint.", "500": "Processing failed.", "503": "Service temporarily unavailable." }, "apis": [ { "name": "feedreader_api", "method": "GET", "path": "/feedreader_api", "description": "Read an RSS, Atom or RDF feed and return all entries as normalized JSON results.", "instructions_url": "https://c7dev.com/api_instructions?api=feedreader_api", "request": { "parameter_location": "query", "parameters": { "url": { "type": "string", "required": true, "description": "Public HTTP(S) RSS, Atom or RDF feed URL. URL-encode the complete value, including any feed query string.", "maxLength": 8192 }, "debug": { "type": "string", "required": false, "description": "Set to 1 for request diagnostics; omit for ordinary requests.", "enum": [ "0", "1" ] } } }, "response": { "format": "application/json", "response_fields": [ "url", "final_url", "http_code", "results", "response", "cached", "fetched_at", "cache_expires_at", "retry_after" ], "item_fields": [ "item_html", "url", "title", "text", "image_url", "time_publicated" ], "headers": { "X-API-Version": "feedreader_api_v8" } }, "details": { "URL": "Required public HTTP(S) feed URL; redirects are followed", "Returns": "results with item_html, url, title, text, image_url and time_publicated", "Errors": "error and error_message, plus the upstream URL, HTTP status, headers and body in response, capped at 100 KiB of original response data", "Caching": "Feed responses are cached for 30 minutes across clients; cached requests do not contact the source", "Refresh": "Expired feeds use ETag or Last-Modified when available; HTTP 304 retains the entries for another 30 minutes", "Reddit": "Uncached feeds share upstream rate limits, with a 60-second fallback when rate headers are absent; cached feeds remain available", "Limits": "40 MiB downloaded/decompressed feed, 20-second request budget and up to five redirects" }, "notes": [ "GET with url returns every entry in the downloaded feed in source order. No result filtering, database writes or deduplication is performed.", "error=false and error_message=\"\" indicate success; results contains the entries. The normal result/error/server_time envelope is also returned.", "debug=1 adds a fresh XML runtime self-test in debug, even when the feed response is cached. It reports PHP/libxml versions and the results of parsing a fixed XML sample; it does not expose configuration, credentials or filesystem contents.", "Feed responses, including upstream errors, are cached for 30 minutes across clients. cached reports cache reuse; fetched_at and cache_expires_at are UTC timestamps and remain unchanged on cache hits. A cached request does not contact the upstream server.", "HTTP 429 rate limits from any source honor Retry-After as seconds or an HTTP date. If that delay exceeds 30 minutes, the cached rate-limit response is retained until the delay expires. retry_after counts down on cache hits; a longer source delay is never shortened to the normal cache lifetime.", "After expiry, feeds with ETag or Last-Modified validators are checked conditionally. If the source returns HTTP 304 Not Modified, the API returns HTTP 200 with the previous entries, http_code=304 and cached=false, and starts a new 30-minute cache period. fetched_at records the latest successful fetch or revalidation. Validators are sent only to the exact feed URL that supplied them.", "Reddit feed cache entries are shared across equivalent subreddit URL spellings. Uncached Reddit feeds share rate limits derived from Retry-After and X-Ratelimit headers. A conservative 60-second interval is used when those headers are absent. Authenticated Data API quotas are not applied to RSS.", "Local Reddit cooldowns return HTTP 429 and retry_after with a Retry-After header. They are not cached for 30 minutes; retry after the indicated delay. Cached feeds remain available during cooldowns. Upstream HTTP 429 responses retain their diagnostics and are cached like other upstream responses.", "Each result preserves the sample contract: item_html is the original entry XML, url is its resolved HTTP(S) link, title and text are plain text, image_url is a resolved image URL, and time_publicated is a Unix timestamp or 0 when unavailable.", "Images use direct feed media fields first, then fall back to img elements, video posters and image-file URLs in content, descriptions, summaries and the original entry XML. Emoji assets and candidates with a declared width or height below 100 pixels are skipped. Only HTTP(S) image URLs are returned; image files are not downloaded to measure unknown dimensions.", "Relative links are resolved against the final feed URL and xml:base. title is limited to 255 characters and image_url to 1000 characters. Missing strings are empty.", "Feed retrieval and parsing failures return HTTP 424 Failed Dependency, error=true, an explanatory error_message, results=[], and the last available upstream response. HTTP 424 preserves JSON diagnostics through gateways that replace HTTP 502 bodies with HTML. http_code retains the upstream status, including 502 when returned by the source. Invalid input returns HTTP 400; when no request completed, response is null.", "On failure, response contains url, http_code, headers, headers_encoding, body, body_encoding, truncated and transport_error. headers is the raw HTTP status/header block. Headers and body together preserve at most 102400 bytes of original response data; truncated identifies omitted data.", "body_encoding and headers_encoding are utf-8 or base64. Decode base64 to recover original non-UTF-8 bytes. JSON escaping and base64 may make the encoded JSON larger than the original response limit.", "Successful responses have response=null. Challenge pages, access denials, rate limits, empty responses and invalid feed XML produce specific error messages. An empty valid feed succeeds with results=[].", "Feeds are limited to 40 MiB of transfer and decompressed data, 32 KiB of response headers per request, five redirects and a 20-second overall request budget. Requests verify TLS and accept only public Internet addresses, including after redirects.", "The parser rejects XML document types and entity declarations and repairs known formatting defects: adjacent namespace declarations and scripts appended after the closing feed element." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/feedreader_api?url=https%3A%2F%2Ffeeds.bbci.co.uk%2Fnews%2Frss.xml" } ] } ], "result": true, "error": false, "error_message": "", "server_time": 1792401583 }