API Documentation

The URLPreview API allows you to retrieve clean, structured metadata for any public URL, including title, description, images, and favicon.

Base Endpoint

GET https://app.urlpreview.com/api/v1/preview

Authentication

You can authenticate in one of two ways:

Authorization: Bearer YOUR_API_KEY

You can find your API key in your dashboard after signing up.

Query Parameters

Example Request (Query)

curl "https://app.urlpreview.com/api/v1/preview?url=https://example.com&apiKey=YOUR_API_KEY"

Example Request (Bearer Token)

curl -H "Authorization: Bearer YOUR_API_KEY" \
"https://app.urlpreview.com/api/v1/preview?url=https://example.com"

Example Response

{
    "url": "https://example.com",
    "title": "Example Domain",
    "description": "This domain is for use in illustrative examples in documents.",
    "image": "https://example.com/og-image.jpg",
    "favicon": "https://example.com/favicon.ico",
    "provider": "generic",
    "details": null
}

Provider & Details

Every response includes a provider field that indicates the source of the metadata. This is always lowercase for consistency and easy querying.

Some providers (like youtube, Twitter/X) may also include a details object with additional structured fields. The exact fields depend on the provider. (This field is only available in starter plan and higher.)

Example (YouTube)

{
    "title": "Why It Was Almost Impossible to Make the Blue LED",
    "description": "The blue LED was supposed to be impossible—until a young engineer proposed a moonshot idea. Head to https://brilliant.org/veritasium to start your free 30-da...",
    "image": "https://i.ytimg.com/vi/AF8d72mA41M/maxresdefault.jpg",
    "icon": "https://www.youtube.com/s/desktop/e5522eef/img/logos/favicon_32x32.png",
    "url": "https://www.youtube.com/watch?v=AF8d72mA41M",
    "provider": "youtube",
    "details": {
        "id": "AF8d72mA41M",
        "type": "video",
        "title": "Why It Was Almost Impossible to Make the Blue LED",
        "duration": {
            "text": "33:45",
            "seconds": 2025,
            "iso8601": "PT33M45S"
        },
        "author": {
            "name": "Veritasium",
            "url": "http://www.youtube.com/@veritasium"
        },
        "metrics": {
            "views": 36538715,
            "likes": 885665
        },
        "publishedAt": "2024-02-08T08:12:09-08:00",
        "extra": {
            "genre": "Education",
            "keywords": "veritasium, science, physics, leds, blue leds, nakamura, invention, discovery, almost impossible, impossible, lighting, technology"
        }
    }
}

Example (Twitter/X)

{
  "title": "X",
  "description": "We’re heartbroken by the loss of Mikeal Rogers, a key figure in the Node.js ecosystem and a force behind so much of what makes this community what it is.\n\nTo help preserve his legacy, we’ve opened a GitHub repo for stories, photos, and memories: https://github.com/nodejs/mikeal\n\nMikeal believed in building human systems, not just software. If he impacted your life, we’d love for you to share something there.\n\n Thank you, Mikeal.\n\nhttps://hubs.la/Q03t0DVL0",
  "image": "https://abs.twimg.com/rweb/ssr/default/og/image.png",
  "icon": "https://x.com/favicon.ico",
  "url": "https://x.com/nodejs/status/1936095262738686378",
  "siteName": "X (formerly Twitter)",
  "provider": "twitter",
  "details": {
      "id": "1936095262738686378",
      "type": "post",
      "content": "We’re heartbroken by the loss of Mikeal Rogers, a key figure in the Node.js ecosystem and a force behind so much of what makes this community what it is.\n\nTo help preserve his legacy, we’ve opened a GitHub repo for stories, photos, and memories: https://github.com/nodejs/mikeal\n\nMikeal believed in building human systems, not just software. If he impacted your life, we’d love for you to share something there.\n\n Thank you, Mikeal.\n\nhttps://hubs.la/Q03t0DVL0",
      "publishedAt": "2025-06-20T16:14:16.000Z",
      "author": {
          "name": "Node.js",
          "username": "@nodejs",
          "verified": true
      },
      "metrics": {
          "likes": 606,
          "replies": 25,
          "reposts": 103,
          "bookmarks": 17
      },
      "media": [
          {
              "url": "https://pbs.twimg.com/media/Gt5kKGkXYAEZNbe?format=png&name=small"
          }
      ],
      "extra": {
          "hashtags": [],
          "keywords": ""
      }
  }
}

Usage Limits

Your plan determines your monthly quota:

Error Handling

On error, the API responds with a JSON object containing an error field. 

{
    "error": "Invalid or unreachable URL"
}

Support

For help, contact us at support@urlpreview.com.