oEmbed Discovery & Response Auditor

Audits a public page for oEmbed discovery and validates the discovered endpoint response against the oEmbed 1.0 specification. oEmbed lets a site embed rich representations of other sites' content (photos, videos, and rich HTML widgets) by auto-discovering a provider endpoint through a <link rel="alternate"> tag and fetching a small structured JSON (or XML) response.

Use cases

• CMS, blogging platform, and link-preview engineering teams verifying their own oEmbed discovery and endpoint are spec-conformant before launch or after a template change.
• Embedding-client and widget developers validating third-party oEmbed providers before integrating them.
• SEO and content-tooling consultants auditing a client's social/embed readiness as part of a broader technical audit.
• CI/CD pipelines validating /.well-known-adjacent oEmbed discovery after reverse-proxy, CMS, or template changes.

Input

Field	Type	Required	Description
startUrl	string	yes	Public page URL to audit for oEmbed discovery links, e.g. a blog post or media page.
endpointOverride	string	no	If set, skip HTML discovery and directly validate this oEmbed endpoint URL instead.
timeoutSeconds	integer	no	Request timeout, 3-30 seconds. Default 10.
maxResponseBytes	integer	no	Max bytes read from the page HTML and the oEmbed response body. Default 1000000 (1 MB).

Output

One JSON object per run, pushed to the default dataset.

Field	Type	Description
inputUrl	string	The page URL provided as input.
pageFinalUrl	string|null	Final page URL after redirects (null if endpointOverride was used).
discoveryLinks	array	Discovered <link rel="alternate"> oEmbed tags: type, href, resolvedUrl, title.
endpointTested	boolean	Whether an oEmbed endpoint URL was found (or supplied) and tested.
endpointUrl	string|null	The oEmbed endpoint URL that was tested.
endpointStatus	integer|null	HTTP status code returned by the endpoint.
endpointHttps	boolean	Whether the endpoint was served over HTTPS.
endpointContentType	string|null	Content-Type header returned by the endpoint.
isXmlResponse	boolean	Whether the response was the XML oEmbed format rather than JSON.
jsonValid	boolean	Whether the JSON response body parsed successfully.
oembedType	string|null	Declared type member: photo, video, link, or rich.
oembedVersion	string|null	Declared version member.
fieldValidationIssues	array	Spec violations found in the response fields.
checks	array	Per-check breakdown: name, status, note, weight, recommendation.
issues	array	Deduplicated list of all issues found.
score	integer	Readiness score, 0-100.
grade	string	Letter grade, A+ to F.
checkedAt	string	ISO timestamp of the audit.
recommendations	array	Actionable fixes.
error	string|null	Top-level page-fetch error, if any.

Example input

{
  "startUrl": "https://www.flickr.com/photos/bees/2341623661/",
  "timeoutSeconds": 10
}

Example output

{
  "inputUrl": "https://www.flickr.com/photos/bees/2341623661/",
  "discoveryLinks": [
    {
      "type": "application/json+oembed",
      "href": "https://www.flickr.com/services/oembed/?url=...&format=json",
      "resolvedUrl": "https://www.flickr.com/services/oembed/?url=...&format=json",
      "title": "oEmbed Profile"
    }
  ],
  "endpointTested": true,
  "endpointStatus": 200,
  "endpointHttps": true,
  "endpointContentType": "application/json; charset=utf-8",
  "isXmlResponse": false,
  "jsonValid": true,
  "oembedType": "photo",
  "oembedVersion": "1.0",
  "fieldValidationIssues": [],
  "score": 100,
  "grade": "A+",
  "issues": [],
  "recommendations": ["oEmbed discovery and response look spec-conformant. Re-run this audit after template/provider changes to catch regressions."]
}

What the spec requires

Per the oEmbed 1.0 specification:

• A provider page SHOULD declare discovery via <link rel="alternate" type="application/json+oembed" href="..."> (and optionally a second link with type="text/xml+oembed") so embedding clients can find the endpoint without hardcoded provider logic.
• The oEmbed endpoint response is a JSON (or XML) object with required type (photo, video, link, or rich) and version ("1.0") members.
• type: photo responses require url, width, and height.
• type: video and type: rich responses require html, width, and height.
• type: link responses require only type and version; other optional members (title, author_name, author_url, provider_name, provider_url, cache_age, thumbnail_url, thumbnail_width, thumbnail_height) MAY be present on any type and must have the documented types when present.

Security

• Public HTTP/HTTPS only. URL credentials are rejected.
• Localhost and private/link-local IPv4 and IPv6 literal ranges (RFC 1918, RFC 3927, and IPv6 unique-local/link-local equivalents, including bracketed IPv6 literals) are blocked.
• Hostnames are DNS-resolved and resolved addresses are re-checked against the same private-range rules before any request is made (SSRF defense in depth).
• Redirects are manually followed and each hop is revalidated with the same SSRF checks before the next request is made (max 3 hops).
• Response bodies (both the page HTML and the oEmbed endpoint body) are capped at maxResponseBytes (default 1 MB).
• Only the audited page and the one discovered (or supplied) oEmbed endpoint URL are ever fetched; no other links found in the page or response are fetched by this actor.
• No login, no credential collection, no private-data extraction.

Pricing

Event	Price (USD)
Actor start	$0.005
Page audited	$0.01

Apify takes a 20% platform commission; the operator keeps 80%.

FAQ

What if a page has no oEmbed discovery link at all? The audit still runs, scores the missing-discovery check as a hard miss, and returns a recommendation to publish a discovery link. No endpoint is tested in that case.

What if I already know the oEmbed endpoint URL and don't want HTML discovery? Set endpointOverride to the exact endpoint URL (including any url= query parameter your provider requires); the actor will skip page discovery and validate that endpoint directly.

Does this actor support the XML oEmbed format? It detects XML responses by Content-Type and reports it, but field-level validation (required members per type) is only performed on the JSON format, since JSON is the format recommended by the current spec and used by the overwhelming majority of real-world providers.

Why does type: link score 100 with so few fields? The oEmbed spec genuinely requires only type and version for the link type; this actor does not penalize spec-compliant minimal responses.