# 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. ``` example.com ``` ## 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.