GET/preview

Unfurl a URL into link card metadata

Fetches the URL and returns the metadata needed to render a link card. Fields with no available source return null rather than a guess.

The url in the response is the final destination after redirects — store that rather than the URL you submitted.

$0.001 per call120 req/minFree allowance applies

Request

curl -X GET "https://www.twotic.dev/v1/link-preview/preview" \
  -H "Authorization: Bearer $TWOTIC_KEY"

const res = await fetch("https://www.twotic.dev/v1/link-preview/preview", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.TWOTIC_KEY}`,
  },
})

if (!res.ok) throw new Error(await res.text())

const data = await res.json()
console.log(res.headers.get("X-Twotic-Cost"))

import os, requests

res = requests.get(
    "https://www.twotic.dev/v1/link-preview/preview",
    headers={"Authorization": f"Bearer {os.environ['TWOTIC_KEY']}"},
)
res.raise_for_status()

data = res.json()
print(res.headers["X-Twotic-Cost"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://www.twotic.dev/v1/link-preview/preview", nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("TWOTIC_KEY"))

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	out, _ := io.ReadAll(res.Body)
	fmt.Println(string(out))
	fmt.Println(res.Header.Get("X-Twotic-Cost"))
}

<?php
$ch = curl_init("https://www.twotic.dev/v1/link-preview/preview");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "GET",
    CURLOPT_HTTPHEADER     => [
        "Authorization: Bearer " . getenv("TWOTIC_KEY"),
    ],
]);

$data = json_decode(curl_exec($ch), true);
curl_close($ch);
print_r($data);

require "net/http"
require "json"

uri = URI("https://www.twotic.dev/v1/link-preview/preview")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV.fetch('TWOTIC_KEY')}"

res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |http|
  http.request(req)
end

puts JSON.parse(res.body)
puts res["X-Twotic-Cost"]

{
  "mcpServers": {
    "link-preview": {
      "type": "http",
      "url": "https://www.twotic.dev/api/mcp/link-preview",
      "headers": { "Authorization": "Bearer tk_live_your_key" }
    }
  }
}

Parameters

query parameters

Name	Type	Required	Description
url	string	required	The absolute URL to unfurl.e.g. https://example.com/article

Response

200The link's preview metadata.

{
  "url": "https://example.com/article",
  "type": "article",
  "image": "https://example.com/og/article.png",
  "title": "How we cut inference cost by 80%",
  "author": "Dana Whitfield",
  "locale": "en_US",
  "favicon": "https://example.com/favicon.ico",
  "siteName": "Example Engineering",
  "themeColor": "#0a0a0a",
  "description": "A write-up of the changes that actually mattered.",
  "publishedAt": "2026-06-14T09:00:00Z"
}

As an agent tool

Connect https://www.twotic.dev/api/mcp/link-preview and this endpoint is exposed as the tool link-preview_preview.

Fetch a URL's preview metadata: title, description, image, favicon, site name, author and published date. Choose this when you need to DESCRIBE or display a link — rendering a preview card, saving a bookmark, citing a source — rather than read its content. Requires `url`. Use Web Extract instead if you need the page's actual text.