{ "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": "metadata_api", "method": "GET", "path": "/metadata_api", "description": "Extract page metadata and rank representative images from a public web page.", "instructions_url": "https://c7dev.com/api_instructions?api=metadata_api", "request": { "parameter_location": "query", "parameters": { "url": { "type": "string", "required": true, "description": "Public HTTP(S) page URL. URL-encode the complete value.", "maxLength": 8192 } } }, "response": { "format": "application/json", "response_fields": [ "url", "final_url", "http_code", "metadata", "cached", "fetched_at", "cache_expires_at", "retry_after" ], "headers": { "X-API-Version": "metadata_api_v3" } }, "details": { "Access": "Requires an access token authorized for metadata_api", "URL": "Required public HTTP(S) page URL; local/private destinations and unsafe redirects are rejected", "Returns": "metadata with title, description, language, site_name, type, canonical_url, author, dates, keywords, image_url and up to five ranked images", "Images": "Declared images, structured data and page context are considered; tiny CDN variants are excluded and matching variants retain the highest observed resolution/quality", "Telegram": "Post widgets provide album photos and video posters; channel avatars and social-card fallbacks are excluded, and posts without confirmed media have no images", "News proxies": "Supported article proxy links must resolve to the publisher; unresolved wrapper pages return an error", "Fallback": "When no credible main image is found, image_url is empty and images contains up to five candidates with confidence scores", "Limits": "5 MiB HTML, 20-second request budget, five redirects; static HTML only, without JavaScript execution", "Caching": "Successful metadata is cached for 30 minutes across clients; failures for at least one minute" }, "notes": [ "Requires an access token authorized for metadata_api, using Authorization: Bearer TOKEN, X-Access-Token, or access_token. Include domain when required by the client configuration.", "Accepts GET and HEAD. Credentials in the target URL, non-HTTP schemes, local hostnames, private/reserved IPs and mixed public/private DNS answers are rejected. Every redirect is validated and connections are pinned to an approved IP with TLS verification.", "Returns metadata with title, description, language, site_name, type, canonical_url, author, published_at, modified_at, keywords, image_url, image_source, image_confidence and images. Missing strings are empty; dates are ISO 8601 when available. Language uses the declared page language or locale; no text-language inference is performed.", "Images consider Open Graph, Twitter cards, JSON-LD, image_src, article/main/figure context, hero markers, title/alt relevance, declared dimensions, srcset, picture, lazy-loading attributes, video posters and inline backgrounds. Up to five distinct candidates include image_url, source, width, height, alt, score and confidence. Dimensions come from declarations, srcset or explicit CDN URL resizing instructions; image files are not downloaded to measure them.", "Small CDN variants, including width/height instructions embedded in paths or query parameters, are rejected even when the HTML declares a larger size. Variants of the same image are combined, retaining the highest observed resolution and then quality. The selected URL is returned intact with its signatures and other parameters; distinct image identifiers remain separate.", "Public Telegram post links also inspect the post widget within the original fetch budget. Images come only from media attached to the requested post; channel avatars, social-card fallback images, quoted-message thumbnails and neighboring posts are excluded. Up to five album photos or video posters are returned. Tile layout sizes are not reported as intrinsic image dimensions. Text-only posts and posts whose widget is unavailable retain their text metadata with image_url empty and images=[].", "Supported news proxy article links must resolve to the original publisher through HTTP redirects or explicit document source declarations. Unresolved wrappers return HTTP 424 with metadata=null. This page-specific rule does not change shared HTTP or feed reader behavior.", "Emoji, icons, logos, avatars, tracking pixels, placeholders, hidden elements, images below 100 declared pixels in either dimension, extreme aspect ratios, navigation, sidebars and related-content images are skipped. image_url is empty when all remaining candidates have low confidence; images then provides up to five alternatives. Fewer candidates are returned when fewer qualify.", "Static HTML only: scripts are not executed and external stylesheets or images are not fetched. JavaScript-only metadata may be unavailable. Relative metadata and image links honor the first HTML base URL and final response URL.", "Successful results cache for 30 minutes across clients. Failures cache for 60 seconds or the longer Retry-After delay. cached, fetched_at and cache_expires_at describe cache reuse. HTTP responses use no-store and X-API-Version.", "Invalid URL input returns HTTP 400. Retrieval, non-HTML, challenge and parsing failures return HTTP 424 with metadata=null; upstream rate limits return HTTP 429. http_code retains the upstream status and retry_after is also sent as Retry-After when positive.", "Limits: 5 MiB of transfer/decompressed HTML per page, 32 KiB headers per request, five HTTP redirects per page and a 20-second fetch budget shared by supplementary page lookups. Only page HTML is fetched." ], "examples": [ { "method": "GET", "url": "https://c7dev.com/metadata_api?url=https%3A%2F%2Fexample.com" } ] } ], "result": true, "error": false, "error_message": "", "server_time": 1794514375 }