# Omnillink: full documentation
An open-source API that turns a URL into metadata, screenshots, PDFs, custom fields and readable content.
# Five-minute quick start
One GET request, one URL as a parameter. This guide takes you from the first call to an integration that handles errors.
## 1. First call
No sign-up and no key are needed. Pass the address of the page in url, URL-encoded.
```
curl "https://omnillink.kayzen-lyon.com/api/v1/meta?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"
```
The answer is a JSON envelope: status, the result in data, and meta, which says whether the answer came from the cache, which path read the page and how long it took.
## 2. In your code
```
const params = new URLSearchParams({ url: "https://example.com/blog/launch" });
const response = await fetch(`https://omnillink.kayzen-lyon.com/api/v1/meta?${params}`);
const body = await response.json();
if (body.status !== "success") {
throw new Error(`${body.code}: ${body.message}`);
}
console.log(body.data.title, body.data.image?.url);
```
Rely on body.code to handle an error: it is stable, whereas message is meant for humans. The full list is in Error codes.
## 3. A screenshot in a tag
/screenshot returns the image itself, so its address works directly in a src attribute.
```
```
## 4. Text for a model
/content returns the readable part of the page. With format=markdown, the answer is the Markdown itself, without a JSON envelope.
```
curl "https://omnillink.kayzen-lyon.com/api/v1/content?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch&format=markdown"
```
## 5. What next
- Try every parameter in the playground, which generates the matching code.
- Read the API reference for the details of parameters and responses.
- Check the limits and quotas before going to production.
- Host your own instance with the self-hosting guide.
# Self-hosting
Omnillink is free software under the MIT licence. You need Node.js 22 or newer; Redis is optional.
## With Node.js
```
git clone https://github.com/kayzen-lyon/linkforge.git
cd linkforge
npm install
npx playwright-core install chromium
cp .env.example .env
npm run dev
```
The API listens on http://localhost:3000. npm run build then npm start run the compiled version.
## On Vercel
The repository contains the configuration of a single serverless function deployment that serves both the API and this site. The root directory of the Vercel project is apps/api.
- On Vercel, Chromium comes from the @sparticuz/chromium package, which is made for serverless functions.
- Without Redis the cache lives in memory, per instance. Add REDIS_URL to share it.
- The first render of a cold instance is slower: Chromium has to start first.
## Environment variables
All of them are optional. The defaults suit a local trial.
- PORT, HOST | 3000, 0.0.0.0 | Listening address.
- REDIS_URL | empty | Shared cache. Empty: in-memory cache.
- API_KEYS | empty | Keys accepted in x-api-key, comma-separated, 16 to 256 characters.
- RATE_LIMIT_MAX | 60 | Requests per window and per IP address.
- RATE_LIMIT_KEY_MAX | 600 | Requests per window and per key.
- RATE_LIMIT_WINDOW_MS | 60000 | Length of the window.
- CACHE_*_TTL_SECONDS | 3600 | Cache lifetime per endpoint: META, SCREENSHOT, PDF, EXTRACT, CONTENT.
- HTTP_TIMEOUT_MS | 10000 | Timeout of the HTTP read.
- BROWSER_NAVIGATION_TIMEOUT_MS | 20000 | Navigation timeout in Chromium.
- BROWSER_MAX_CONCURRENCY | 4 | Pages rendered in parallel (2 on serverless).
- REQUEST_DEADLINE_MS | 55000 | Overall deadline of a request.
- SSRF_ALLOWED_PORTS | 80,443 | Allowed destination ports.
- SSRF_BLOCKED_HOSTS | empty | Extra refused destinations, host or host:port. This list can only restrict.
- BROWSER_PAGE_MAX_REQUESTS | 1500 | Requests at most per rendered page.
- BROWSER_PAGE_MAX_BYTES | 60 MB (30 on serverless) | Bytes received at most per rendered page.
- CIRCUIT_BREAKER_THRESHOLD | 5 | Consecutive network failures before a host is set aside.
- CIRCUIT_BREAKER_COOLDOWN_MS | 30000 | How long it is set aside.
- ANIMATION_MAX_BYTES | 10 MB (4 on serverless) | Maximum size of an animated capture.
- METRICS_TOKEN | empty | Token that protects /metrics (Prometheus format). Empty: the route does not exist.
- MCP_ENABLED | true | Turns on the MCP endpoint POST /mcp.
- CORS_ORIGIN | * | Origins allowed to call the API from a browser.
SSRF_ALLOW_PRIVATE_NETWORKS=true allows local and private addresses. It exists for tests: the API refuses to start with it when NODE_ENV=production.
## Checking the installation
```
curl http://localhost:3000/health
```
The answer gives the uptime, the cache backend and the state of the browser pool. The Status page shows the same for this instance.
# TypeScript SDK and the link-preview element
The repository contains a dependency-free TypeScript client and a custom element. Both live in packages/sdk.
The @omnillink/sdk package is built from the repository. Its publication on the npm registry is not confirmed at this time: until then, install it from packages/sdk.
## The client
```
import { createClient } from '@omnillink/sdk';
const omnillink = createClient({ baseUrl: 'https://omnillink.kayzen-lyon.com' });
const { data, meta } = await omnillink.meta('https://example.com/blog/launch');
console.log(data.title, data.image?.url, meta.cached);
```
- baseUrl | – | Origin of the instance. /api/v1 is appended for you.
- apiKey | – | Sent in the x-api-key header.
- fetch | global fetch | Your own implementation, for tests for instance.
- timeoutMs | 30000 | Time allowed for a whole request. 0 disables it.
The meta, extract, content, screenshot and pdf methods take the parameters of the API. The JSON methods resolve to { data, meta }.
## The element
A separate entry point registers the element. It renders a preview card from /meta.
```
```
## React
The @omnillink/react package, in packages/react, provides the component and the useLinkMeta() hook. The component wraps the element with typed props. On the server it renders a plain link; in the browser it becomes the card.
```
import { LinkPreview } from '@omnillink/react';
;
```
## GitHub Action
The .github/actions/link-preview action fetches the metadata of an address, exposes it as step outputs and writes a preview to the job summary. It can also take a screenshot.
```
- uses: kayzen-lyon/linkforge/.github/actions/link-preview@main
id: preview
with:
url: https://example.com/blog/launch
base-url: https://omnillink.kayzen-lyon.com
- run: echo "$TITLE"
env:
TITLE: ${{ steps.preview.outputs.title }}
```
The playground generates this tag for the address you are testing. The options are detailed in the README.md of the package.
# Omnillink for AI agents
A language model reads raw HTML badly: menus, scripts and banners drown the text. /content gives it the readable part of the page.
## Markdown in one request
```
curl "https://omnillink.kayzen-lyon.com/api/v1/content?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch&format=markdown"
```
- format=json (default) returns title, excerpt, text, markdown, wordCount, readingTimeMinutes, plus the links and images of the content.
- format=markdown and format=text return the text alone, ready to drop into a prompt.
- citations=true replaces links with numbered references, with the list of addresses at the end.
- mainContent=false keeps the whole page instead of the main content only; include and exclude take CSS selectors.
## Keeping the size under control
Text and Markdown are cut at 500,000 characters; the truncated field reports it. wordCount lets you estimate the cost of a call before sending the text to a model.
## Turning it into a tool
The OpenAPI document describes every endpoint with its parameters: most agent frameworks can derive a tool definition from it.
```
curl "https://omnillink.kayzen-lyon.com/api/v1/openapi.json"
```
## MCP server
The Model Context Protocol lets an agent call Omnillink as a set of tools. There are two ways to connect: an endpoint hosted by the instance, and a local server started by your client.
### Hosted endpoint
POST /mcp speaks the stateless HTTP transport: one JSON-RPC 2.0 message per request, a JSON answer, no session. Methods: initialize, ping, tools/list and tools/call. One tool call counts as one request of the quota; x-api-key is honoured.
```
curl -X POST "https://omnillink.kayzen-lyon.com/mcp" \
-H "content-type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```
### Local server (stdio)
The @omnillink/mcp package, in packages/mcp, is an MCP server over stdio, started by your client. It needs Node.js 20 or newer.
- omnillink_content | Read an article or a documentation page | Markdown, in parts when long
- omnillink_meta | Identify a link: title, description, image, feeds | JSON
- omnillink_extract | Pull precise values with CSS selectors | JSON
- omnillink_screenshot | See a page | An image
- omnillink_pdf | Keep a page as a file | The path of the saved PDF
```
claude mcp add \
--env OMNILLINK_URL=https://links.example.com \
--env OMNILLINK_API_KEY=your-key \
omnillink -- npx -y @omnillink/mcp
```
```
{
"mcpServers": {
"omnillink": {
"command": "npx",
"args": [
"-y",
"@omnillink/mcp"
],
"env": {
"OMNILLINK_URL": "https://links.example.com",
"OMNILLINK_API_KEY": "your-key"
}
}
}
}
```
- Claude Desktop: Settings, Developer, Edit Config (claude_desktop_config.json).
- Cursor: ~/.cursor/mcp.json for all projects, or .cursor/mcp.json for one.
- OMNILLINK_URL names your instance; without it the server uses the demo instance. OMNILLINK_API_KEY requires OMNILLINK_URL: the server refuses to send a key to the default instance.
- From a checkout of the repository, replace npx -y @omnillink/mcp with node /absolute/path/to/packages/mcp/dist/bin.js. Publication of the package on the npm registry is not confirmed at this time.
## llms.txt files
This site publishes /llms.txt, a table of contents of the documentation, and /llms-full.txt, which holds its full text in a single file.
Extracted content comes from a third-party site. Treat it as untrusted data: it may contain instructions meant to hijack an agent.
# Recipes
Four common uses, with the minimal code for each.
## Link previews in a blog
Call /meta at publication time, or on the server, and keep the result with the article. You do not call the API on every visit.
```
async function linkCard(url) {
const params = new URLSearchParams({ url });
const response = await fetch(`https://omnillink.kayzen-lyon.com/api/v1/meta?${params}`);
const { status, data } = await response.json();
if (status !== "success") return null;
return {
title: data.title ?? new URL(data.url).hostname,
description: data.description,
image: data.image?.url ?? null,
site: data.publisher,
};
}
```
## Share images
Capture a page designed for the purpose, at the size social networks expect. selector limits the capture to one element.
```
```
## Price monitoring
Describe the fields once; call the same request at regular intervals. ttl sets how long the answer stays cached.
```
curl -G "https://omnillink.kayzen-lyon.com/api/v1/extract" \
--data-urlencode "url=https://example.com/product/42" \
--data-urlencode 'fields={"name":{"selector":"h1"},"price":{"selector":".price","type":"number"}}' \
--data-urlencode "ttl=900"
```
## PDF archiving
/pdf renders the page with its print stylesheet. force=true guarantees a copy of the page as it is at that moment.
```
curl -o archive.pdf "https://omnillink.kayzen-lyon.com/api/v1/pdf?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch&format=A4&force=true"
```
Check that you are allowed to copy and keep the pages you archive or collect.
# Error codes
Every error has the same JSON shape, including on the endpoints that return an image or a PDF.
```
{
"status": "fail",
"code": "EFORBIDDENURL",
"message": "Destination is not allowed"
}
```
- status is fail when the request is at fault (4xx), error when the server or the target is at fault (5xx).
- code is stable: it is what your code should test.
- message is in English, meant for humans, and may change.
## Causes and fixes
- EINVALIDPARAMS | 400 | A parameter is missing or has an invalid value. | Compare the request with the reference; the message names the parameter.
- EINVALIDURL | 400 | The url is malformed or is neither http nor https. | Send an absolute address and encode it (encodeURIComponent).
- EUNAUTHORIZED | 401 | The key sent in x-api-key is not known to the instance. | Fix the key, or remove the header for an anonymous call.
- EFORBIDDENURL | 403 | The destination is private, local or internal, or its port is not allowed. | Only public pages can be read. For an intranet, host your own instance inside that network.
- EEMBEDNOTFOUND | 404 | The path requested with embed does not exist for this page, or is null. | Call /meta without embed to see the available fields; plan a fallback image.
- ESELECTORNOTFOUND | 404 | The selector matches no visible element. | Check the selector in a browser; add waitForSelector if the element appears late.
- ENOTHTML | 422 | The target is an image, a PDF or another file, not an HTML page. | Use this endpoint on a page; /screenshot accepts other types.
- ETOOLARGE | 422 | The PDF or the generated output exceeds the maximum size. | Make the page smaller: turn printBackground off, or target a shorter page.
- ERATELIMIT | 429 | Too many requests in the current window. | Wait for the retry-after delay. Cache your results, or use a key.
- EBROWSER | 500 | Chromium crashed or could not start. | Retry. If the error persists on your instance, check the Chromium installation.
- EINTERNAL | 500 | Unexpected server error. | Retry; if it happens again, open an issue with the x-request-id header of the response.
- EUNREACHABLE | 502 | The target site does not answer: unknown name, refused connection, TLS error. | Check the address in a browser. The site may be down or blocking bots.
- ETARGETSTATUS | 502 | The target site answered with an HTTP error (404, 403, 500…). | The message gives the status. Check that the page exists and is public.
- EBLOCKED | 502 | The site served an anti-bot block page instead of its content. | Omnillink does not work around these protections. Check the page in a browser, or ask the site for access.
- ECIRCUITOPEN | 503 | The target site failed several times in a row; it is set aside for a few seconds. | Retry after the delay given by the retry-after header.
- EBUSY | 503 | Too many renders are queued on the instance. | Retry after a few seconds, with an increasing delay.
- ETIMEOUT | 504 | The target site did not answer in time. | Retry. For a slow page, render=never avoids the browser.
## When to retry
- Retry EBUSY, ECIRCUITOPEN, ETIMEOUT, EUNREACHABLE, EBROWSER and EINTERNAL, with an increasing delay.
- Retry ERATELIMIT after the delay given by the retry-after header.
- Do not retry the other 4xx codes: the same request will give the same error.
# Limits and quotas
These are the defaults of the software. The operator of an instance can change some of them; those are listed with their variable.
## Request rate
- Requests per minute, without a key (per IP address) | 60 | RATE_LIMIT_MAX
- Requests per minute, with a key (per key) | 600 | RATE_LIMIT_KEY_MAX
- Addresses per /meta/batch call | 10 | –
The x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset headers come with every response. The playground shows the remaining quota after each call.
## Sizes
- Length of url | 2,048 characters | –
- Body of a page read over HTTP | 5 MB | HTTP_MAX_BODY_BYTES
- Height of a full-page screenshot | 12 000 px | –
- Screenshot viewport | 320 to 2560 px wide, 240 to 2160 px high | –
- Pages of a PDF | 100 | –
- Size of a PDF | 10 MB (4 MB on serverless) | PDF_MAX_BYTES
- Fields of an extraction | 20 fields, 100 values per field, 10,000 characters per value | –
- Text of /content | 500,000 characters, 500 links, 200 images | –
## Durations
- HTTP read | 10 s | HTTP_TIMEOUT_MS
- Navigation in Chromium | 20 s | BROWSER_NAVIGATION_TIMEOUT_MS
- Whole request | 55 s | REQUEST_DEADLINE_MS
- waitFor wait | 0 to 10,000 ms | –
- Redirects followed | 5 | HTTP_MAX_REDIRECTS
- Cache lifetime | 1 h; ttl from 60 to 86,400 s | CACHE_*_TTL_SECONDS
# Security
An API that visits addresses supplied by its users is a classic target. Here is what the software does, and what it does not do.
## The threat: SSRF
In an SSRF attack, someone asks the server to read an address they cannot reach themselves: an internal service, the admin interface of a router, or the metadata service of a cloud host.
## What is covered
- Only http and https are accepted, without credentials in the address, on a list of allowed ports (80 and 443 by default).
- localhost, internal names and any address that is not publicly routable are refused: private ranges, loopback, link-local including 169.254.169.254, CGNAT, IPv6 ULA, IPv4-mapped addresses.
- Unusual notations, such as 0x7f.1 or 2130706433, are normalised before the check.
- A single private DNS record is enough to refuse a host name.
- Over HTTP, the validated DNS resolution is pinned to the connection, and every redirect is validated again.
- In the browser, two layers: every request the page makes is intercepted and validated, and the only network exit Chromium has is a proxy inside the API. On every connection, redirects included, that proxy applies the policy, resolves the name itself and connects to the address it has just validated.
- The API runs no code supplied by the caller. The only "programmable" inputs are CSS selectors, with bounds.
- Only Accept-Language, User-Agent and Referer can be set towards the target. Cookie and Authorization are excluded, because answers are cached per address.
- What comes from a page stays data: /html is served as plain text, the html field of /oembed is never interpreted, CSV output neutralises formulas.
## What is not covered
- The content of the pages read is not filtered: treat every answer as untrusted data, and never inject it as is into HTML.
- The API does not check that you are allowed to read, copy or keep a page. That responsibility is yours.
- The validating proxy lives in the same process as the API: it does not replace egress filtering at network level (firewall, VPC), which remains recommended as defence in depth.
- A render runs the JavaScript of the page in Chromium. The protection is about reachable destinations, not about what the page does once loaded.
- Quota counters are not a protection against distributed denial of service.
- The repository README and SECURITY.md have the details.
## This site
- It loads no third-party script and sets no cookies.
- API answers are never interpreted as HTML here: they are displayed as text.
- The API key typed in the playground stays in memory in the tab; it is neither saved nor added to share links.
## Reporting a vulnerability
Write to contact@kayzen-lyon.fr rather than opening a public issue. The /.well-known/security.txt file gives the same contact.
# Glossary
The terms of this documentation, in a few words.
- Open Graph: og:* tags a page declares to describe its title, image and summary when it is shared.
- Twitter Cards: twitter:* tags, the equivalent of Open Graph tags for the X network.
- JSON-LD: A block of structured data, in JSON, that describes the content of a page with the schema.org vocabulary.
- oEmbed: A format through which a site says how to embed one of its contents: a video player, for example.
- Link preview: A card shown in place of an address: title, description, image and site name.
- Canonical URL: The address a page names as its reference version.
- SSRF: Server-Side Request Forgery: an attack that makes a server read an internal address on behalf of the attacker.
- DNS rebinding: An attack where a domain name first answers with a public address, then with an internal one.
- Headless browser: A browser driven by a program, without a window. Omnillink uses Chromium.
- Rendering: Running the JavaScript of a page in a browser, to get the content a visitor would see.
- Single-page app: A site whose initial HTML is almost empty and whose content is built by JavaScript.
- TTL: Time To Live: how long a result stays in the cache.
- De-duplication: Grouping identical simultaneous requests into a single run.
- OpenAPI: A format that describes an HTTP API, readable by tools that generate clients or documentation from it.
- CSS selector: An expression that designates elements of a page, such as .price or article h1.
# Changelog
This page is generated from the repository history. It keeps new features (feat) and fixes (fix) only, in the wording of the commits.
## 18 November 2026
- feat MCP endpoint, page insights, extraction presets, tables, oEmbed, QR, palette and more
- feat premium site — flag language selector, playground, guides, search
- feat developer tooling — CLI, MCP server, React wrapper, GitHub Action, examples
- feat site tools — links, rendered HTML, technologies, image facts, sitemap, link check
- fix validate every browser connection through an in-process egress proxy
- fix ignore unknown query parameters instead of rejecting the request
- feat Omnillink site, extended API and SDK
- fix install every workspace on Vercel so the playground can build
- fix deploy as a single Fastify service that also serves the playground
- fix make the Vercel build pick the right API entry point
- fix configure Vercel services for the API and the playground
- feat deploy on Vercel instead of Docker
- feat bootstrap LinkForge link intelligence API
# API reference
Every endpoint is a GET request under /api/v1. The examples use the address of this instance.
### GET /api/v1/meta
Returns the normalised metadata of a page, merged from Open Graph, Twitter Cards, JSON-LD, standard HTML tags and feeds. Use it to build link previews, enrich bookmarks or index pages. A field the page does not provide is null, or an empty array for lists.
- url (string, required): Absolute address of the page, http or https, URL-encoded. At most 2,048 characters, without credentials.
- render (auto | never | always, default auto): auto reads the page over HTTP and opens a browser only when the result is poor. never stays on HTTP. always renders the page in the browser every time. See Rendering.
- force (boolean, default false): Skips the cache read and processes the page again. The new result is still stored.
- ttl (integer): How long the result is kept in the cache, in seconds, from 60 to 86,400. It also sets the duration announced in cache-control. Without this parameter the server default applies. See Caching.
- embed (string): Dot path to a URL inside data, such as image.url, logo.url, favicon or images.0.url. Instead of JSON, the API answers with a redirect to that URL, so the request works directly in a src attribute. When the path is absent or null, the API answers EEMBEDNOTFOUND (404).
### GET /api/v1/screenshot
Renders the page in a headless browser and returns the image itself, not JSON. The request address works directly in a src attribute.
- url (string, required): Absolute address of the page, http or https, URL-encoded. At most 2,048 characters, without credentials.
- device (desktop | mobile, default desktop): desktop uses a 1280 × 800 viewport. mobile emulates a phone (Pixel 7 profile: touch screen, mobile user agent, high pixel density).
- width (integer): Viewport width in CSS pixels, from 320 to 2560. Overrides the device preset.
- height (integer): Viewport height in CSS pixels, from 240 to 2160. Overrides the device preset.
- fullPage (boolean, default false): Captures the whole scrollable page instead of the viewport, up to 12,000 px high. Ignored with selector.
- selector (string): CSS selector: only the first matching element is captured. When it matches no visible element, the API answers ESELECTORNOTFOUND (404).
- format (png | jpeg, default png): Format of the returned image.
- quality (integer, default 80): JPEG quality, from 1 to 100. No effect on PNG.
- colorScheme (light | dark): Value of prefers-color-scheme reported to the page. Without this parameter nothing is forced.
- hide (string): CSS selectors to hide before the capture, separated by commas, 20 at most. Handy for cookie banners: hide=.cookie-banner,#newsletter.
- waitFor (integer, default 0): Extra wait before the capture, in milliseconds, from 0 to 10,000.
- force (boolean, default false): Skips the cache read and processes the page again. The new result is still stored.
- ttl (integer): How long the result is kept in the cache, in seconds, from 60 to 86,400. It also sets the duration announced in cache-control. Without this parameter the server default applies. See Caching.
### GET /api/v1/pdf
Renders the page in a headless browser, with its print stylesheet, and returns it as a PDF document. The document has 100 pages at most; above the maximum size the API answers ETOOLARGE (422).
- url (string, required): Absolute address of the page, http or https, URL-encoded. At most 2,048 characters, without credentials.
- format (A4 | Letter, default A4): Paper size.
- landscape (boolean, default false): Landscape orientation instead of portrait.
- printBackground (boolean, default true): Includes background colours and images.
- force (boolean, default false): Skips the cache read and processes the page again. The new result is still stored.
- ttl (integer): How long the result is kept in the cache, in seconds, from 60 to 86,400. It also sets the duration announced in cache-control. Without this parameter the server default applies. See Caching.
### GET /api/v1/extract
Extracts the fields you describe. fields is a URL-encoded JSON object that maps each field name to a rule. The response uses the same names with the extracted values.
- url (string, required): Absolute address of the page, http or https, URL-encoded. At most 2,048 characters, without credentials.
- fields (string (JSON), required): URL-encoded JSON object: one rule per output field, 20 fields at most. The properties of a rule are described below.
- render (auto | never | always, default auto): auto reads the page over HTTP and opens a browser only when the result is poor. never stays on HTTP. always renders the page in the browser every time. See Rendering.
- force (boolean, default false): Skips the cache read and processes the page again. The new result is still stored.
- ttl (integer): How long the result is kept in the cache, in seconds, from 60 to 86,400. It also sets the duration announced in cache-control. Without this parameter the server default applies. See Caching.
### GET /api/v1/content
Returns the readable part of a page, without navigation, ads or boilerplate, as plain text and as Markdown. Made for AI agents, summarisation and indexing.
- url (string, required): Absolute address of the page, http or https, URL-encoded. At most 2,048 characters, without credentials.
- render (auto | never | always, default auto): auto reads the page over HTTP and opens a browser only when the result is poor. never stays on HTTP. always renders the page in the browser every time. See Rendering.
- force (boolean, default false): Skips the cache read and processes the page again. The new result is still stored.
- ttl (integer): How long the result is kept in the cache, in seconds, from 60 to 86,400. It also sets the duration announced in cache-control. Without this parameter the server default applies. See Caching.