Migrate to OpenGraph.io oEmbed

Before you migrate

OpenGraph.io is not a byte-for-byte clone of Iframely or Embedly. Both competitors excel at curated provider networks. OpenGraph.io adds a third resolution tier: when no native or discovery embed exists, a hosted fallback card is generated from page metadata (source: og_frame).

Endpoint mapping

Replace your provider URL with the OpenGraph.io oEmbed endpoint:

GET https://opengraph.io/api/3.0/oembed?url={encoded_url}&app_id=YOUR_APP_ID

Path-encoded form is also supported: /api/3.0/oembed/{encoded_url}. Use whichever fits your HTTP client.

Step-by-step migration

1. 1. Create an OpenGraph.io account

   Sign up and copy your App ID from the dashboard. This replaces your Iframely/Embedly API key.

2. 2. Swap the request URL

   Point your server or CMS integration at OpenGraph.io. Pass the target URL as ?url= (recommended for migrations) or as a path segment.

   Before (generic oEmbed proxy)

   Copy

   const res = await fetch(`${OLD_PROVIDER}/oembed?url=${encodeURIComponent(targetUrl)}&api_key=...`);
   const data = await res.json();
   container.innerHTML = data.html;

   After (OpenGraph.io)

   Copy

   const res = await fetch(
     `https://opengraph.io/api/3.0/oembed?url=${encodeURIComponent(targetUrl)}&app_id=${APP_ID}`
   );
   const data = await res.json();
   container.innerHTML = data.html; // same field, embed-ready HTML

3. 3. Handle the source field

   Check data.source to label embeds in your UI or analytics:

   • native: known oEmbed provider
   • discovery: page advertised an oEmbed endpoint
   • og_frame: hosted OpenGraph fallback card

4. 4. Store embed_id for fallback frames

   When source is og_frame, the response includes embed_id and frame_url. Store embed_id to refresh stale cards later via the Frame Management API.

5. 5. Test with cache_ok=false

   During migration validation, append &cache_ok=false to force fresh metadata fetches and compare output against your previous provider.

Response field reference

Standard oEmbed fields are preserved. OpenGraph.io adds:

• source: resolver tier (native | discovery | og_frame)
• embed_id: stable UUID when source is og_frame
• frame_url: direct iframe URL for hosted fallback cards

See the full API reference: oEmbed API docs.

Refresh hosted embeds

After migration, refresh fallback cards without re-supplying the original URL:

curl -X POST "https://frames.opengraph.io/api/v1/frames/YOUR_EMBED_ID/refresh?app_id=YOUR_APP_ID"

Related resources