API reference
Every endpoint is a GET request under /api/v1. The examples use the address of this instance.
Quick start
Pass the address of the page in the url parameter, URL-encoded. No key is needed to get started.
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.
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:
| Header | Description |
|---|---|
x-ratelimit-limit | Number of requests allowed in the window. |
x-ratelimit-remaining | Number of requests left in the current window. |
x-ratelimit-reset | Seconds until the window resets. |
retry-after | Present 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.
{
"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.
{
"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)
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
curl "https://omnillink.kayzen-lyon.com/api/v1/meta?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"
{
"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
}
}
<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)
| Parameter | Type | Default | Description |
|---|---|---|---|
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.
curl -o screenshot.png \
"https://omnillink.kayzen-lyon.com/api/v1/screenshot?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch&device=mobile&colorScheme=dark"
<img src="https://omnillink.kayzen-lyon.com/api/v1/screenshot?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch&format=jpeg" alt="example.com" />
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)
| Parameter | Type | Default | Description |
|---|---|---|---|
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.
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)
| Parameter | Type | Default | Description |
|---|---|---|---|
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).
{
"price": {
"selector": ".price",
"attr": "text",
"type": "number"
},
"links": {
"selector": "a",
"attr": "href",
"type": "url",
"all": true
}
}
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}}'
{
"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)
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
curl "https://omnillink.kayzen-lyon.com/api/v1/content?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"
{
"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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
curl "https://omnillink.kayzen-lyon.com/api/v1/tables?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"
Links of a page
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
url required |
string |
Absolute http(s) URL of the target page. |
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
| Parameter | Type | Default | Description |
|---|---|---|---|
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": { … } }. |
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.
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.
curl "https://omnillink.kayzen-lyon.com/health"
{
"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.
{
"status": "fail",
"code": "EFORBIDDENURL",
"message": "Destination is not allowed"
}
| Code | HTTP | status | Meaning |
|---|---|---|---|
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
httpandhttpsare 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 including169.254.169.254, CGNAT, IPv6 ULA, IPv4-mapped addresses. Unusual notations such as0x7f.1are 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.