On this page

API reference

Every endpoint is a GET request under /api/v1. The examples use the address of this instance.

Playgroundopenapi.json

Quick start

Pass the address of the page in the url parameter, URL-encoded. No key is needed to get started.

Request
curl "https://omnillink.kayzen-lyon.com/api/v1/meta?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

JSON responses share the same envelope. /screenshot and /pdf return the file itself.

Authentication

The API works without authentication. The optional x-api-key header identifies your application and raises its rate limit.

Request
curl -H "x-api-key: $OMNILLINK_API_KEY" \
  "https://omnillink.kayzen-lyon.com/api/v1/meta?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

Keys are defined by the operator of the instance, with the API_KEYS variable. When the instance declares keys, an unknown key is rejected with the EUNAUTHORIZED code (HTTP 401): the request is not treated as anonymous. When it declares none, the header is ignored.

Rate limits

Without a key, requests are counted per IP address: 60 per minute by default. With a valid key they are counted per key: 600 per minute by default. The operator sets these values with RATE_LIMIT_MAX, RATE_LIMIT_KEY_MAX and RATE_LIMIT_WINDOW_MS.

Beyond the limit, the API answers with status 429 and the ERATELIMIT code. These headers let you see it coming:

HeaderDescription
x-ratelimit-limitNumber of requests allowed in the window.
x-ratelimit-remainingNumber of requests left in the current window.
x-ratelimit-resetSeconds until the window resets.
retry-afterPresent on a 429 response: seconds to wait before retrying.

/health is not rate limited.

Response format

A success returns status: "success", the result in data and information about the processing in meta.

Response
{
  "status": "success",
  "data": {
    "url": "https://example.com/blog/launch",
    "title": "Launching the new editor"
  },
  "meta": {
    "cached": true,
    "source": "http",
    "durationMs": 3
  }
}
Field Type Description
meta.cached boolean true when the response comes from the cache.
meta.source http | browser http when a plain HTTP request was enough, browser when the page was rendered in Chromium.
meta.durationMs integer Server-side processing time, in milliseconds.

A failure returns status: "fail" when the request is at fault (4xx statuses) or "error" when the server or the target is at fault (5xx statuses), with a stable code and a readable message. The full list is in Errors.

Response
{
  "status": "fail",
  "code": "EFORBIDDENURL",
  "message": "Destination is not allowed"
}

Caching

Every result is cached on the server, under a key that depends on the URL and the parameters. By default it stays there for one hour; the operator can change that duration, and the ttl parameter sets it for a given request.

force=true skips the cache read and processes the page again. The new result replaces the old one.

The x-cache header is HIT or MISS, and meta.cached repeats that in JSON responses. Responses also carry a cache-control header with max-age and s-maxage, so a browser or a CDN can reuse them.

Identical requests received at the same time are grouped: the page is processed only once.

Rendering

/meta, /extract and /content first read the page with a plain HTTP request, which is fast and cheap. With render=auto, a headless browser only starts when that first pass gives a poor result, or when the page is an empty single-page-app shell.

render=never guarantees a fast answer. render=always suits pages built entirely with JavaScript. /screenshot and /pdf always go through the browser.

Default limits: 10 s for the HTTP request, 20 s for browser navigation, 5 redirects and 5 MB of response body. The operator can change them.

Endpoints

Metadata

GET/api/v1/meta

Returns application/json

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.

Query parameters

Parameter Type Default Description
url required string Default Absolute address of the page, http or https, URL-encoded. At most 2,048 characters, without credentials.
render auto | never | always Defaultauto 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 Defaultfalse Skips the cache read and processes the page again. The new result is still stored.
ttl integer Default 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 Default 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).

More parameters (OpenAPI document)

ParameterTypeDefaultDescription
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.

Fields of data

Field Type Description
url string Final address, after redirects.
canonicalUrl string | null Canonical address declared by the page.
title string | null Page title.
description string | null Description or summary.
author string | null Author.
publisher string | null Name of the site or publisher.
lang string | null Declared language, for example en.
date string | null Publication date, in ISO 8601 format.
image object | null Main image: url, width, height, type, alt.
images object[] Every image found, in the same format as image.
favicon string | null Address of the site icon.
logo object | null Best brand icon, as url: the logo declared in JSON-LD, otherwise the largest icon of the page.
video object | null Main video: url, type, width, height.
audio object | null Main audio track: url, type.
keywords string[] Declared keywords.
feeds object[] RSS or Atom feeds advertised by the page: url, title, type.
jsonLd object[] JSON-LD blocks of the page, with @graph flattened.
contentType string | null Content type returned by the target.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/meta?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"
Response
{
  "status": "success",
  "data": {
    "url": "https://example.com/blog/launch",
    "canonicalUrl": "https://example.com/blog/launch",
    "title": "Launching the new editor",
    "description": "What changed in the editor, and how to migrate your documents.",
    "author": "Ada Example",
    "publisher": "Example Blog",
    "lang": "en",
    "date": "2025-03-04T09:00:00.000Z",
    "image": {
      "url": "https://example.com/img/launch.png",
      "width": 1200,
      "height": 630,
      "type": "image/png",
      "alt": "The new editor"
    },
    "images": [
      {
        "url": "https://example.com/img/launch.png",
        "width": 1200,
        "height": 630,
        "type": "image/png",
        "alt": "The new editor"
      }
    ],
    "favicon": "https://example.com/favicon.ico",
    "logo": {
      "url": "https://example.com/logo.png"
    },
    "video": null,
    "audio": null,
    "keywords": [
      "editor",
      "release"
    ],
    "feeds": [
      {
        "url": "https://example.com/feed.xml",
        "title": "Example Blog",
        "type": "application/rss+xml"
      }
    ],
    "jsonLd": [
      {
        "@type": "BlogPosting",
        "headline": "Launching the new editor"
      }
    ],
    "contentType": "text/html"
  },
  "meta": {
    "cached": false,
    "source": "http",
    "durationMs": 132
  }
}
A field used as an image
<img src="https://omnillink.kayzen-lyon.com/api/v1/meta?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch&embed=image.url" alt="" />

Screenshot

GET/api/v1/screenshot

Returns image/png | image/jpeg

Renders the page in a headless browser and returns the image itself, not JSON. The request address works directly in a src attribute.

Query parameters

Parameter Type Default Description
url required string Default Absolute address of the page, http or https, URL-encoded. At most 2,048 characters, without credentials.
device desktop | mobile Defaultdesktop desktop uses a 1280 × 800 viewport. mobile emulates a phone (Pixel 7 profile: touch screen, mobile user agent, high pixel density).
width integer Default Viewport width in CSS pixels, from 320 to 2560. Overrides the device preset.
height integer Default Viewport height in CSS pixels, from 240 to 2160. Overrides the device preset.
fullPage boolean Defaultfalse Captures the whole scrollable page instead of the viewport, up to 12,000 px high. Ignored with selector.
selector string Default CSS selector: only the first matching element is captured. When it matches no visible element, the API answers ESELECTORNOTFOUND (404).
format png | jpeg Defaultpng Format of the returned image.
quality integer Default80 JPEG quality, from 1 to 100. No effect on PNG.
colorScheme light | dark Default Value of prefers-color-scheme reported to the page. Without this parameter nothing is forced.
hide string Default CSS selectors to hide before the capture, separated by commas, 20 at most. Handy for cookie banners: hide=.cookie-banner,#newsletter.
waitFor integer Default0 Extra wait before the capture, in milliseconds, from 0 to 10,000.
force boolean Defaultfalse Skips the cache read and processes the page again. The new result is still stored.
ttl integer Default 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.

More parameters (OpenAPI document)

ParameterTypeDefaultDescription
hideBanners boolean true Hide common cookie / consent banners before the capture, with a built-in stylesheet (nothing is clicked, no consent is given).
blockAds boolean false Drop requests to a built-in list of well-known advertising and tracking hosts (faster, cleaner captures). Not a full ad blocker.
waitForSelector string CSS selector that must be present in the DOM before the page is read or captured (at most 10 s, bounded by the request deadline). CSS only. Not found in time: 404 ESELECTORNOTFOUND.
click string CSS selector of one element to click before the capture (open a tab, expand a section). A real click on the first visible match; not found within 3 s: 404 ESELECTORNOTFOUND. CSS only, no script.
scrollTo string CSS selector of an element to scroll into view before the capture. Not found within 3 s: 404 ESELECTORNOTFOUND.
frame none | browser | phone none Device frame drawn around the capture: a browser window or a phone bezel. Composed offline from the finished capture. Not available with fullPage.
radius integer 0–64 0 Corner radius of the capture, in pixels.
padding integer 0–200 0 Space around the capture, in pixels, filled with background.
background string ffffff Colour behind the capture when frame, radius or padding is used: hexadecimal RGB, RRGGBB or RRGGBBAA, with or without #. 00000000 is transparent (PNG).
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.

Errors are still returned as JSON, with the matching HTTP status. Check the status, or the content-type header, before treating the body as an image.

Request
curl -o screenshot.png \
  "https://omnillink.kayzen-lyon.com/api/v1/screenshot?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch&device=mobile&colorScheme=dark"
In an image tag
<img src="https://omnillink.kayzen-lyon.com/api/v1/screenshot?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch&format=jpeg" alt="example.com" />

PDF

GET/api/v1/pdf

Returns application/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).

Query parameters

Parameter Type Default Description
url required string Default Absolute address of the page, http or https, URL-encoded. At most 2,048 characters, without credentials.
format A4 | Letter DefaultA4 Paper size.
landscape boolean Defaultfalse Landscape orientation instead of portrait.
printBackground boolean Defaulttrue Includes background colours and images.
force boolean Defaultfalse Skips the cache read and processes the page again. The new result is still stored.
ttl integer Default 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.

More parameters (OpenAPI document)

ParameterTypeDefaultDescription
hideBanners boolean false Hide common cookie / consent banners before printing (nothing is clicked).
blockAds boolean false Drop requests to a built-in list of well-known advertising and tracking hosts (faster, cleaner captures). Not a full ad blocker.
waitForSelector string CSS selector that must be present in the DOM before the page is read or captured (at most 10 s, bounded by the request deadline). CSS only. Not found in time: 404 ESELECTORNOTFOUND.
margin integer 0–50 Margin on every side, in millimetres. Default: the page's own @page margins.
scale number 0.1–2 1 Scale of the rendering.
pageRanges string Pages to keep, e.g. 1-3,5 (pages 1 to 100, at most 10 ranges). Default: all.
headerText string Plain text printed at the top of every page. It is escaped (no HTML); the tokens {page}, {pages}, {title}, {url} and {date} are filled in. Forces a top margin of at least 12 mm.
footerText string Plain text printed at the bottom of every page; same rules as headerText. Example: Page {page} / {pages}.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.

As with screenshots, errors are returned as JSON with the matching HTTP status.

Request
curl -o page.pdf \
  "https://omnillink.kayzen-lyon.com/api/v1/pdf?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch&format=Letter&landscape=true"

Extract

GET/api/v1/extract

Returns application/json

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.

Query parameters

Parameter Type Default Description
url required string Default Absolute address of the page, http or https, URL-encoded. At most 2,048 characters, without credentials.
fields required string (JSON) Default 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 Defaultauto 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 Defaultfalse Skips the cache read and processes the page again. The new result is still stored.
ttl integer Default 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.

More parameters (OpenAPI document)

ParameterTypeDefaultDescription
preset article | product | recipe | event Built-in typed fields instead of fields, read from schema.org JSON-LD, then microdata, Open Graph, <meta> tags and a few CSS fallbacks. sources tells where each value came from. article: headline, description, author, authorUrl, publisher, datePublished, dateModified, image, section, keywords, language, wordCount, url. product: name, description, brand, sku, gtin, image, price, currency, availability, condition, ratingValue, reviewCount, seller, url. recipe: name, description, author, image, datePublished, prepMinutes, cookMinutes, totalMinutes, yield, category, cuisine, calories, ingredients, instructions, keywords, ratingValue, ratingCount. event: name, description, startDate, endDate, status, attendanceMode, locationName, address, image, organizer, performers, price, currency, availability, url.
waitForSelector string CSS selector that must be present in the DOM before the page is read or captured (at most 10 s, bounded by the request deadline). CSS only. Not found in time: 404 ESELECTORNOTFOUND.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.

Properties of a rule

Property Type Default Description
selector required string Default CSS selector of the element to read, 300 characters at most.
attr string Defaulttext text for the text of the element, html for its HTML content, or the name of an attribute such as href, src or content.
type string Defaultstring Conversion applied to the raw value: string, number (numeric value) or url (absolute address, resolved from the page address).
all boolean Defaultfalse Returns an array of every match, 100 at most, instead of the first one only.

A field is null when nothing matches or the value cannot be converted. Strings are cut at 10,000 characters.

/meta, /extract and /content need an HTML document: for an image, a PDF or any other file type, the API answers ENOTHTML (422).

Rules
{
  "price": {
    "selector": ".price",
    "attr": "text",
    "type": "number"
  },
  "links": {
    "selector": "a",
    "attr": "href",
    "type": "url",
    "all": true
  }
}
Request
curl -G "https://omnillink.kayzen-lyon.com/api/v1/extract" \
  --data-urlencode "url=https://example.com/blog/launch" \
  --data-urlencode 'fields={"price":{"selector":".price","attr":"text","type":"number"},"links":{"selector":"a","attr":"href","type":"url","all":true}}'
Response
{
  "status": "success",
  "data": {
    "url": "https://example.com/blog/launch",
    "fields": {
      "price": 49.9,
      "links": [
        "https://example.com/",
        "https://example.com/pricing"
      ]
    }
  },
  "meta": {
    "cached": false,
    "source": "http",
    "durationMs": 118
  }
}

Content

GET/api/v1/content

Returns application/json

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.

Query parameters

Parameter Type Default Description
url required string Default Absolute address of the page, http or https, URL-encoded. At most 2,048 characters, without credentials.
render auto | never | always Defaultauto 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 Defaultfalse Skips the cache read and processes the page again. The new result is still stored.
ttl integer Default 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.

More parameters (OpenAPI document)

ParameterTypeDefaultDescription
format json | markdown | text json json: the envelope. markdown / text: the body alone, as text/markdown or text/plain, ready to be piped into a prompt.
mainContent boolean true Keep only the main content. false keeps the whole <body> (scripts and styles aside).
include string Comma-separated CSS selectors: keep only the matching elements (document order). Replaces main-content detection. At most 20 selectors of 200 characters.
exclude string Comma-separated CSS selectors of elements to remove before extraction. At most 20 selectors of 200 characters.
citations boolean false Reference-style links in markdown: [label][1] in the text, the numbered URLs at the end.
waitForSelector string CSS selector that must be present in the DOM before the page is read or captured (at most 10 s, bounded by the request deadline). CSS only. Not found in time: 404 ESELECTORNOTFOUND.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.

Fields of data

Field Type Description
url string Final address, after redirects.
title string | null Title of the content.
lang string | null Language declared by the page.
excerpt string | null Short excerpt or description.
text string Content as plain text.
markdown string The same content as Markdown: headings, lists, links, code.
wordCount integer Number of words in the content.
readingTimeMinutes integer Estimated reading time in minutes, at 200 words per minute, rounded up.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/content?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"
Response
{
  "status": "success",
  "data": {
    "url": "https://example.com/blog/launch",
    "title": "Launching the new editor",
    "lang": "en",
    "excerpt": "What changed in the editor, and how to migrate your documents.",
    "text": "Launching the new editor\n\nToday we are releasing…",
    "markdown": "# Launching the new editor\n\nToday we are releasing…",
    "wordCount": 742,
    "readingTimeMinutes": 4
  },
  "meta": {
    "cached": false,
    "source": "http",
    "durationMs": 164
  }
}

The sections that follow, and the “More parameters” tables, are generated from the OpenAPI document of the API, in its own wording.

Metadata of several URLs

POST/api/v1/meta/batch

Returns application/json

Metadata of up to 10 URLs in one call, over raw HTTP only (the equivalent of render=never: no browser). Results come back in input order; a URL that fails yields an error item and never fails the batch. Every URL goes through the same validation and anti-SSRF checks as GET /api/v1/meta. The answer is not cacheable by a CDN, but each item reads and feeds the server cache. Rate limit: one tenth of the caller's normal limit, counted separately.

Query parameters

ParameterTypeDefaultDescription
urls required array Absolute http(s) URLs, at most 10. Duplicates are fetched once.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl -X POST "https://omnillink.kayzen-lyon.com/api/v1/meta/batch" \
  -H "content-type: application/json" \
  -d '{"urls":["https://example.com/blog/launch"]}'

Animated scroll-through capture (APNG)

GET/api/v1/animation

Returns image/apng

A short scroll-through of the page as an animated PNG (image/apng), which every current browser plays in an <img> and which degrades to its first frame elsewhere. Frames are viewport captures stitched without re-encoding: no video, no GIF. Bounded: 10 frames, 1280×800 px, and a byte budget (ANIMATION_MAX_BYTES): frames stop being added when it is reached (x-animation-frames tells how many made it); if two frames do not fit, the answer is 422 ETOOLARGE.

Query parameters

ParameterTypeDefaultDescription
url required string Absolute http(s) URL of the target page.
width integer 320–1280 800 Viewport width in CSS pixels.
height integer 240–800 500 Viewport height in CSS pixels.
frames integer 2–10 6 Frames wanted, evenly spaced from the top to the bottom of the page (12 000 px at most).
delay integer 100–3000 800 Display time of each frame, in milliseconds.
hideBanners boolean true Hide common cookie / consent banners (nothing is clicked).
blockAds boolean false Drop requests to well-known advertising and tracking hosts.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl -o animation.png "https://omnillink.kayzen-lyon.com/api/v1/animation?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

HTML tables as JSON or CSV

GET/api/v1/tables

Returns application/json | text/csv

The data tables of a page as rows of text: headers detected, colspan and rowspan expanded, layout tables skipped. format=csv exports one table as RFC 4180 CSV; cells that a spreadsheet would run as a formula (=, +, -, @) are prefixed with an apostrophe. With render=auto the browser is used when the static markup holds no table.

Query parameters

ParameterTypeDefaultDescription
url required string Absolute http(s) URL of the target page.
render auto | never | always auto Browser rendering strategy. auto: raw HTTP, then a headless browser only when needed. never: raw HTTP only. always: always render.
selector string CSS selector restricting which <table> elements are read (e.g. #prices, table.specs).
format json | csv json json: every table in the envelope. csv: one table (see table) as text/csv.
table integer 0–19 0 With format=csv: index of the table to export, as numbered in the JSON answer.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/tables?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

GET/api/v1/links

Returns application/json

Every <a href> of a page: absolute, de-duplicated, in document order, with its text, rel tokens and whether it stays on the site. With render=auto the browser is used when the page runs scripts and its static markup is nearly empty or contains no link.

Query parameters

ParameterTypeDefaultDescription
url required string Absolute http(s) URL of the target page.
render auto | never | always auto Browser rendering strategy. auto: raw HTTP, then a headless browser only when needed. never: raw HTTP only. always: always render.
scope all | internal | external all Keep every link, or only those on / off the page's own host.
limit integer 1–2000 500 Most links returned. truncated tells when more matched.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/links?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

Rendered HTML of a page

GET/api/v1/html

Returns text/plain

The HTML document of a page once rendered by a browser, as text. The answer is third-party markup: it is served as text/plain with nosniff, so a browser never interprets it on this origin. Treat it as untrusted input. Capped at the server's body limit (5 MB by default).

Query parameters

ParameterTypeDefaultDescription
url required string Absolute http(s) URL of the target page.
render auto | never | always always always (default): the DOM serialised after scripts have run. never: the markup as served. auto: served markup unless it is an empty shell.
waitForSelector string CSS selector that must be present in the DOM before the page is read or captured (at most 10 s, bounded by the request deadline). CSS only. Not found in time: 404 ESELECTORNOTFOUND.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/html?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

Technologies of a page

GET/api/v1/tech

Returns application/json

CMS, framework, libraries, UI kit, build tool, analytics, CDN, hosting, e-commerce platform… recognised from the response headers, the generator tag, asset URLs, cookie names, markers in the markup, runtime markers in the first-party bundles and, when rendered, a fixed built-in probe of the running page. Every detection comes with its evidence, a confidence level and a version when the evidence states one. A product that leaves no trace is not listed: the answer never guesses.

Query parameters

ParameterTypeDefaultDescription
url required string Absolute http(s) URL of the target page.
render auto | never | always auto never: response headers, markup and first-party bundles only. always: also the rendered DOM and a fixed, built-in probe of well-known globals and runtime markers (never caller-supplied code). auto: the browser only when the static markup is an empty shell in which no framework or library was recognised.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/tech?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

Page weight, timings and web vitals (lab)

GET/api/v1/insights

Returns application/json

Loads the page once in a headless browser and reports what that load cost: total transfer size, requests and bytes by resource type, third-party hosts, TTFB, DOMContentLoaded, load, FCP, LCP and CLS, plus the technologies seen. Every number is a lab measurement from a single load in a data-centre browser — no throttling, cold cache — not a field score and not a Lighthouse audit. Use force=true to measure again.

Query parameters

ParameterTypeDefaultDescription
url required string Absolute http(s) URL of the target page.
device desktop | mobile desktop desktop: 1280×800. mobile: Pixel 7 profile (UA, DPR, touch). No network or CPU throttling is applied in either case.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/insights?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

Best icon of a site

GET/api/v1/favicon

Returns application/json

Collects the icons a page declares (<link rel="icon">, apple-touch-icon, web app manifest) plus /favicon.ico, measures up to 8 of them from their first 128 KB (never decoding pixels) and returns the largest real raster icon, or a vector one when there is no raster. Declared sizes are not trusted: dimensions are read from the files. Icons are returned as they are: no resizing.

Query parameters

ParameterTypeDefaultDescription
url required string Absolute http(s) URL of the target page.
redirect boolean false true: answer with a 302 to the best icon instead of JSON, so the URL works as an <img src>.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/favicon?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

oEmbed resolution

GET/api/v1/oembed

Returns application/json

Follows the oEmbed discovery link a page advertises (<link type="application/json+oembed">, XML accepted) and returns a normalised document: type, title, author, provider, thumbnail, dimensions, html. The endpoint is chosen by the page, so it goes through the same anti-SSRF checks as any target. html is untrusted third-party markup, returned as a string. A page that advertises no endpoint answers 404 EEMBEDNOTFOUND: there is no built-in provider list.

Query parameters

ParameterTypeDefaultDescription
url required string Absolute http(s) URL of the target page.
maxWidth integer 1–4096 Passed to the provider as maxwidth.
maxHeight integer 1–4096 Passed to the provider as maxheight.
acceptLanguage string Accept-Language sent to the target, e.g. fr-FR,fr;q=0.9. Applied on the raw HTTP path and in the browser; part of the cache key.
userAgent string User-Agent sent to the target (printable ASCII). Part of the cache key. Cookies and Authorization cannot be set: answers are cached by URL and shared between callers.
referer string Referer sent with the document request: an absolute http(s) URL. Part of the cache key.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/oembed?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

Colour palette of an image

GET/api/v1/palette

Returns application/json

Dominant colours of an image, or of the main preview image of a page. An 8-bit PNG is decoded in process (meta.source: http); any other format is decoded by the headless browser through the guarded path (meta.source: browser), which costs a render. Computed by recursive splitting of the colour space on a sample of at most 20 000 pixels.

Query parameters

ParameterTypeDefaultDescription
url required string URL of an image, or of a page: the palette of its main preview image (og:image…) is then returned.
count integer 2–8 5 Colours wanted (a flat image yields fewer).
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/palette?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

QR code of a URL

GET/api/v1/qr

Returns image/svg+xml | image/png

The QR code of a URL as SVG (default) or PNG, usable directly as an <img src>. Computed locally: the URL is never requested. The smallest symbol that fits is chosen; a URL too long for the requested error-correction level answers 400.

Query parameters

ParameterTypeDefaultDescription
url required string Absolute http(s) URL to encode. It is only encoded, never fetched.
format svg | png svg
size integer 64–2048 512 Width and height of the image, in pixels.
margin integer 0–16 4 Quiet zone around the code, in modules (the standard asks for 4).
ecc L | M | Q | H M Error-correction level: L ~7 %, M ~15 %, Q ~25 %, H ~30 % of the code can be damaged.
color string 000000 Colour of the modules: hexadecimal RGB, RRGGBB or RRGGBBAA, with or without #.
background string ffffff Background colour, same syntax; 00000000 for transparent. Keep a strong contrast with color or scanners will fail.
Request
curl -o qr.svg "https://omnillink.kayzen-lyon.com/api/v1/qr?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

Social sharing image from text

GET/api/v1/og

Returns image/png | image/jpeg

A 1200×630 social card (og:image) built from text parameters and a built-in template, usable directly in <meta property="og:image">. Rendered by the headless browser from a document generated by the API: no remote resource is loaded, scripts are off, every text is escaped and length-bounded. No URL is fetched by this endpoint.

Query parameters

ParameterTypeDefaultDescription
title required string Headline of the card. Plain text: markup is shown as text, never interpreted.
description string Supporting line under the title (two lines at most are shown).
site string Site or brand name, bottom left.
author string Author or date, bottom right.
label string Small pill above the title (Guide, New).
template classic | gradient | split classic classic: plain card with an accent rule. gradient: accent gradient background. split: accent band on the left.
theme light | dark light
accent string 2563eb Accent colour: hexadecimal RGB or RRGGBB, with or without #.
format png | jpeg png
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl -o og.png "https://omnillink.kayzen-lyon.com/api/v1/og?title=Omnillink"

Real dimensions and weight of an image

GET/api/v1/image

Returns application/json

Format, pixel dimensions and byte size of an image, read from the first 128 KB of the file only (range request): the image is never downloaded in full nor decoded. Given a page URL, measures the page's main preview image (og:image…).

Query parameters

ParameterTypeDefaultDescription
url required string URL of an image, or of a page: its main preview image is then measured.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/image?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

robots.txt and sitemaps of a site

GET/api/v1/sitemap

Returns application/json

Reads /robots.txt, then the sitemaps it declares (/sitemap.xml when it declares none). Index files are followed one level. Bounded: 10 files, the server's body limit per file (gzip accepted, 10 MB once decompressed), limit URLs. A file that cannot be read is reported in sitemaps[].error and does not fail the request.

Query parameters

ParameterTypeDefaultDescription
url required string Any URL of the site (its robots.txt and sitemaps are discovered), or the URL of a sitemap file to read directly.
limit integer 1–5000 500 Most URLs returned in urls. urlCount still counts all of them.
force boolean false Bypass the cache read (the result is still stored).
ttl integer 60–86400 Cache lifetime of this answer, in seconds. Applies to the server cache entry and to Cache-Control. Defaults to the server configuration.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/sitemap?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

Link checker

GET/api/v1/check

Returns application/json

State of a link right now: final status, the redirect chain with status and timing of each hop, the TLS certificate when the last hop is https, declared type and length. Raw HTTP only, bodies are never downloaded, every hop goes through the anti-SSRF checks. An HTTP error of the target is a result (ok: false), not an API error. Never cached. An invalid or expired certificate is reported as EUNREACHABLE.

Query parameters

ParameterTypeDefaultDescription
url required string Absolute http(s) URL of the target page.
Request
curl "https://omnillink.kayzen-lyon.com/api/v1/check?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

Model Context Protocol endpoint

POST/mcp

Returns application/json

MCP server over stateless Streamable HTTP: one JSON-RPC 2.0 message per POST, answered as application/json (no session, no SSE stream; GET answers 405). Methods: initialize, ping, tools/list, tools/call. Tools: meta, content, extract, links, tech, check, sitemap, screenshot. A failed tool call is a normal result with isError: true whose text starts with the Omnillink error code (EBLOCKED: …). Results are bounded and say when they were cut; anything that comes from a page is announced as third-party data. Rate limited like the REST API (one call = one request) and honours x-api-key. A refusal by the HTTP layer (429, 401) is a JSON-RPC error -32000 whose data.code is the Omnillink code.

Query parameters

ParameterTypeDefaultDescription
jsonrpc required string
id string Omit for a notification (answered with 202, no body).
method required initialize | ping | tools/list | tools/call | notifications/initialized
params object For tools/call: { "name": "<tool>", "arguments": { … } }.
Request
curl -X POST "https://omnillink.kayzen-lyon.com/mcp" \
  -H "content-type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

OpenAPI

GET/api/v1/openapi.json

Returns application/json

Returns the OpenAPI 3.1 description of the API, as JSON. Use it to generate a typed client or to import it into your API testing tool.

Request
curl "https://omnillink.kayzen-lyon.com/api/v1/openapi.json"

Service status

GET/health

Returns application/json

Returns the state of the instance: uptime, cache backend in use (memory or redis) and browser pool statistics. This endpoint is not rate limited.

Request
curl "https://omnillink.kayzen-lyon.com/health"
Response
{
  "status": "ok",
  "uptimeSeconds": 5121,
  "cache": "memory",
  "browserPool": {
    "active": 0,
    "queued": 0,
    "maxConcurrency": 4,
    "browserConnected": true
  }
}

Errors

Every error has the same shape on every endpoint, including those that return an image or a PDF. Rely on code, which is stable; message is meant for humans and may change.

Response
{
  "status": "fail",
  "code": "EFORBIDDENURL",
  "message": "Destination is not allowed"
}
CodeHTTPstatusMeaning
EINVALIDPARAMS HTTP400 fail A query parameter is missing, unknown or invalid. This code also comes with the 404 status of an unknown route.
EINVALIDURL HTTP400 fail The url is malformed or uses neither http nor https.
EUNAUTHORIZED HTTP401 fail The key sent in x-api-key is unknown.
EFORBIDDENURL HTTP403 fail The destination is refused by the SSRF policy: private, loopback or metadata address, internal host name, or a port that is not allowed.
EEMBEDNOTFOUND HTTP404 fail The path requested with embed is absent from the /meta response, or is null.
ESELECTORNOTFOUND HTTP404 fail The selector given to /screenshot matches no visible element.
ENOTHTML HTTP422 fail The target is not an HTML document, and this endpoint needs one.
ETOOLARGE HTTP422 fail The generated output exceeds the maximum allowed size.
ERATELIMIT HTTP429 fail Too many requests. Wait for the delay given in the message and in the retry-after header.
EBROWSER HTTP500 error The headless browser crashed or could not start.
EINTERNAL HTTP500 error Unexpected server error. No internal detail is disclosed.
EUNREACHABLE HTTP502 error The target cannot be reached: DNS failure, refused connection, TLS error.
ETARGETSTATUS HTTP502 error The target answered with an HTTP error status.
EBLOCKED HTTP502 error The target answered with an anti-bot block page instead of its content. That answer is never cached.
EBUSY HTTP503 error The rendering queue is full. Retry in a moment.
ECIRCUITOPEN HTTP503 error The target failed several times in a row: it is not contacted for a short while.
ETIMEOUT HTTP504 error The target did not answer in time.

Security model

An API that visits addresses supplied by its users is a classic target for SSRF attacks. Omnillink validates every destination before connecting to it.

  • Only http and https are accepted, without credentials in the address, and 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 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; WebSockets and service workers are cut off. 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.

What is not covered: this 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. The protection is about which destinations the browser can reach, not about what a page does once it is loaded. The repository README has the details.

Keyboard shortcuts

CtrlKor/
Open search and commands
?
Show this help
←→
Move from one tab to the next
Ctrl↵
Run the request in the playground
Esc
Close a panel or a menu

Single-key shortcuts can be turned off in the accessibility options.