embisto documentation

embisto turns a URL into the data a client needs to draw a link preview: title, description, site name, author, publication date, icon, image with its size, video, and the provider's embed HTML. It is a single Go binary with no required external services, and the same code is a Go library.

Try the hosted API

The API answers at api.embisto.com, free and without a key, with 60 requests a minute per IP address. The service runs on a best-effort basis with no uptime promise: use it to try embisto, and run your own for production.

curl 'https://api.embisto.com/v1/preview?url=https://github.com'

The same call from code:

curl 'https://api.embisto.com/v1/preview?url=https%3A%2F%2Fgithub.com'

response, err := http.Get("https://api.embisto.com/v1/preview?url=https%3A%2F%2Fgithub.com")
if err != nil {
	return err
}
defer response.Body.Close()
var card map[string]any
err = json.NewDecoder(response.Body).Decode(&card)

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

var client = HttpClient.newHttpClient();
var request = HttpRequest.newBuilder(URI.create("https://api.embisto.com/v1/preview?url=https%3A%2F%2Fgithub.com")).build();
var card = client.send(request, HttpResponse.BodyHandlers.ofString()).body();
System.out.println(card);

const response = await fetch("https://api.embisto.com/v1/preview?url=https%3A%2F%2Fgithub.com");
const card = await response.json();

import json
from urllib.request import urlopen

with urlopen("https://api.embisto.com/v1/preview?url=https%3A%2F%2Fgithub.com") as response:
    card = json.load(response)
print(card["title"])

require "json"
require "net/http"

card = JSON.parse(Net::HTTP.get(URI("https://api.embisto.com/v1/preview?url=https%3A%2F%2Fgithub.com")))
puts card["title"]

The hosted API fails with the codes of embisto and one of its own:

It does not serve DELETE /v1/preview, which purges a server's cache.

The API reference lists every route with its parameters and answers, and lets you call them from the browser. The spec itself is at https://api.embisto.com/openapi.json.

Run it yourself

Docker

docker run --rm -p 8080:8080 ghcr.io/pantafive/embisto:latest
curl 'localhost:8080/v1/preview?url=https://github.com'

The image is a static binary on a distroless base. :latest is the newest release; :0.3.0 pins one, and :main follows the main branch.

Binary

Each release has static binaries for Linux, macOS and Windows on amd64 and arm64. With Go installed:

go install github.com/pantafive/embisto/cmd/embisto@latest
embisto

Go library

go get github.com/pantafive/embisto

The server is a thin layer over the library: everything the server does, the library does. The Go library shows the API and how to add a site provider or an output format. The source is at github.com/pantafive/embisto.

A server is configured through environment variables, listed in configuration; nothing else needs to run beside it.

Reference

• HTTP API
• Caching
• Configuration
• Hardening
• Iframely compatibility
• The Go library
• Operations
• Output formats from templates
• Thumbnails

Planned

Not built yet, in rough order: providers for more of the most-shared sites; several URLs in one request; an outgoing proxy for sites that refuse data-center addresses; an optional headless browser for pages that need JavaScript; card components for Swift and Kotlin.