Référence de l’API
Tous les points d’accès sont des requêtes GET sous /api/v1. Les exemples utilisent l’adresse de cette instance.
Démarrage rapide
Passez l’adresse de la page dans le paramètre url, encodée pour une URL. Aucune clé n’est nécessaire pour commencer.
curl "https://omnillink.kayzen-lyon.com/api/v1/meta?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"
Les réponses JSON partagent la même enveloppe. /screenshot et /pdf renvoient directement le fichier.
Authentification
L’API s’utilise sans authentification. L’en-tête facultatif x-api-key identifie votre application et relève sa limite de débit.
curl -H "x-api-key: $OMNILLINK_API_KEY" \
"https://omnillink.kayzen-lyon.com/api/v1/meta?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"
Les clés sont définies par l’exploitant de l’instance, avec la variable API_KEYS. Quand l’instance en déclare, une clé inconnue est refusée avec le code EUNAUTHORIZED (HTTP 401) : la requête n’est pas traitée comme anonyme. Quand elle n’en déclare aucune, l’en-tête est ignoré.
Limites de débit
Sans clé, les requêtes sont comptées par adresse IP : 60 par minute par défaut. Avec une clé valide, elles sont comptées par clé : 600 par minute par défaut. L’exploitant règle ces valeurs avec RATE_LIMIT_MAX, RATE_LIMIT_KEY_MAX et RATE_LIMIT_WINDOW_MS.
Au-delà de la limite, l’API répond avec le statut 429 et le code ERATELIMIT. Les en-têtes suivants vous permettent de l’anticiper :
| En-tête | Description |
|---|---|
x-ratelimit-limit | Nombre de requêtes autorisées dans la fenêtre. |
x-ratelimit-remaining | Nombre de requêtes restantes dans la fenêtre en cours. |
x-ratelimit-reset | Secondes avant la remise à zéro de la fenêtre. |
retry-after | Présent sur une réponse 429 : secondes à attendre avant de réessayer. |
/health n’est pas soumis à la limite de débit.
Format des réponses
Une réussite renvoie status: "success", le résultat dans data et des informations sur le traitement dans meta.
{
"status": "success",
"data": {
"url": "https://example.com/blog/launch",
"title": "Launching the new editor"
},
"meta": {
"cached": true,
"source": "http",
"durationMs": 3
}
}
| Champ | Type | Description |
|---|---|---|
meta.cached |
boolean |
true si la réponse vient du cache. |
meta.source |
http | browser |
http si une simple requête HTTP a suffi, browser si la page a été rendue dans Chromium. |
meta.durationMs |
integer |
Durée du traitement côté serveur, en millisecondes. |
Un échec renvoie status: "fail" quand la requête est en cause (statuts 4xx) ou "error" quand le serveur ou la cible est en cause (statuts 5xx), avec un code stable et un message lisible. La liste complète figure dans Erreurs.
{
"status": "fail",
"code": "EFORBIDDENURL",
"message": "Destination is not allowed"
}
Cache
Chaque résultat est mis en cache côté serveur, sous une clé qui dépend de l’URL et des paramètres. Par défaut il y reste une heure ; l’exploitant peut changer cette durée, et le paramètre ttl la règle pour une requête donnée.
force=true ignore la lecture du cache et traite de nouveau la page. Le nouveau résultat remplace l’ancien.
L’en-tête x-cache vaut HIT ou MISS, et meta.cached reprend l’information dans les réponses JSON. Les réponses portent aussi un en-tête cache-control avec max-age et s-maxage, pour qu’un navigateur ou un CDN puisse les réutiliser.
Des requêtes identiques reçues en même temps sont regroupées : la page n’est traitée qu’une seule fois.
Rendu
/meta, /extract et /content lisent d’abord la page par une simple requête HTTP, rapide et peu coûteuse. Avec render=auto, un navigateur sans interface n’est lancé que si ce premier passage donne un résultat pauvre, ou si la page est une coquille d’application monopage vide.
render=never garantit une réponse rapide. render=always convient aux pages entièrement construites en JavaScript. /screenshot et /pdf passent toujours par le navigateur.
Limites par défaut : 10 s pour la requête HTTP, 20 s pour la navigation dans le navigateur, 5 redirections et 5 Mo de corps de réponse. L’exploitant peut les modifier.
Points d’accès
Métadonnées
GET/api/v1/meta
Renvoie application/json
Renvoie les métadonnées normalisées d’une page, fusionnées à partir d’Open Graph, des Twitter Cards, du JSON-LD, des balises HTML standard et des flux. Utile pour construire des aperçus de liens, enrichir des favoris ou indexer des pages.
Un champ que la page ne fournit pas vaut null, ou un tableau vide pour les listes.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
string |
Défaut | Adresse absolue de la page, en http ou https, encodée pour une URL. 2 048 caractères au plus, sans identifiants. |
render |
auto | never | always |
Défautauto |
auto lit la page en HTTP et n’ouvre un navigateur que si le résultat est pauvre. never reste en HTTP. always rend toujours la page dans le navigateur. Voir Rendu. |
force |
boolean |
Défautfalse |
Ignore la lecture du cache et traite de nouveau la page. Le nouveau résultat est tout de même enregistré. |
ttl |
integer |
Défaut | Durée de conservation du résultat dans le cache, en secondes, de 60 à 86 400. Elle fixe aussi la durée annoncée dans cache-control. Sans ce paramètre, la durée par défaut du serveur s’applique. Voir Cache. |
embed |
string |
Défaut | Chemin à points vers une URL de data, par exemple image.url, logo.url, favicon ou images.0.url. Au lieu du JSON, l’API répond par une redirection vers cette URL : la requête s’utilise alors directement dans un attribut src. Si le chemin est absent ou vaut null, l’API répond EEMBEDNOTFOUND (404). |
Autres paramètres (spécification OpenAPI)
| Paramètre | Type | Défaut | 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. |
Champs de data
| Champ | Type | Description |
|---|---|---|
url |
string |
Adresse finale, après redirections. |
canonicalUrl |
string | null |
Adresse canonique déclarée par la page. |
title |
string | null |
Titre de la page. |
description |
string | null |
Description ou résumé. |
author |
string | null |
Auteur. |
publisher |
string | null |
Nom du site ou de l’éditeur. |
lang |
string | null |
Langue déclarée, par exemple fr. |
date |
string | null |
Date de publication, au format ISO 8601. |
image |
object | null |
Image principale : url, width, height, type, alt. |
images |
object[] |
Toutes les images trouvées, au même format que image. |
favicon |
string | null |
Adresse de l’icône du site. |
logo |
object | null |
Meilleure icône de marque, sous la forme url : logo déclaré en JSON-LD, sinon la plus grande icône de la page. |
video |
object | null |
Vidéo principale : url, type, width, height. |
audio |
object | null |
Piste audio principale : url, type. |
keywords |
string[] |
Mots-clés déclarés. |
feeds |
object[] |
Flux RSS ou Atom annoncés par la page : url, title, type. |
jsonLd |
object[] |
Blocs JSON-LD de la page, @graph aplati. |
contentType |
string | null |
Type de contenu renvoyé par la cible. |
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="" />
Capture d’écran
GET/api/v1/screenshot
Renvoie image/png | image/jpeg
Rend la page dans un navigateur sans interface et renvoie l’image elle-même, pas du JSON. L’adresse de la requête s’utilise directement dans un attribut src.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
string |
Défaut | Adresse absolue de la page, en http ou https, encodée pour une URL. 2 048 caractères au plus, sans identifiants. |
device |
desktop | mobile |
Défautdesktop |
desktop utilise une fenêtre de 1280 × 800. mobile émule un téléphone (profil Pixel 7 : écran tactile, agent utilisateur mobile, haute densité de pixels). |
width |
integer |
Défaut | Largeur de la fenêtre en pixels CSS, de 320 à 2560. Remplace celle du profil device. |
height |
integer |
Défaut | Hauteur de la fenêtre en pixels CSS, de 240 à 2160. Remplace celle du profil device. |
fullPage |
boolean |
Défautfalse |
Capture toute la page défilable plutôt que la fenêtre, dans la limite de 12 000 px de haut. Ignoré avec selector. |
selector |
string |
Défaut | Sélecteur CSS : seul le premier élément correspondant est capturé. S’il ne correspond à aucun élément visible, l’API répond ESELECTORNOTFOUND (404). |
format |
png | jpeg |
Défautpng |
Format de l’image renvoyée. |
quality |
integer |
Défaut80 |
Qualité JPEG, de 1 à 100. Sans effet en PNG. |
colorScheme |
light | dark |
Défaut | Valeur de prefers-color-scheme annoncée à la page. Sans ce paramètre, rien n’est imposé. |
hide |
string |
Défaut | Sélecteurs CSS à masquer avant la capture, séparés par des virgules, 20 au plus. Pratique pour les bandeaux de cookies : hide=.cookie-banner,#newsletter. |
waitFor |
integer |
Défaut0 |
Attente supplémentaire avant la capture, en millisecondes, de 0 à 10 000. |
force |
boolean |
Défautfalse |
Ignore la lecture du cache et traite de nouveau la page. Le nouveau résultat est tout de même enregistré. |
ttl |
integer |
Défaut | Durée de conservation du résultat dans le cache, en secondes, de 60 à 86 400. Elle fixe aussi la durée annoncée dans cache-control. Sans ce paramètre, la durée par défaut du serveur s’applique. Voir Cache. |
Autres paramètres (spécification OpenAPI)
| Paramètre | Type | Défaut | 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. |
Les erreurs restent renvoyées en JSON, avec le statut HTTP correspondant. Vérifiez le statut, ou l’en-tête content-type, avant de traiter le corps comme une 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
Renvoie application/pdf
Rend la page dans un navigateur sans interface, avec sa feuille de style d’impression, et la renvoie sous forme de document PDF. Le document compte 100 pages au plus ; au-delà de la taille maximale, l’API répond ETOOLARGE (422).
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
string |
Défaut | Adresse absolue de la page, en http ou https, encodée pour une URL. 2 048 caractères au plus, sans identifiants. |
format |
A4 | Letter |
DéfautA4 |
Format du papier. |
landscape |
boolean |
Défautfalse |
Orientation paysage plutôt que portrait. |
printBackground |
boolean |
Défauttrue |
Inclut les couleurs et les images d’arrière-plan. |
force |
boolean |
Défautfalse |
Ignore la lecture du cache et traite de nouveau la page. Le nouveau résultat est tout de même enregistré. |
ttl |
integer |
Défaut | Durée de conservation du résultat dans le cache, en secondes, de 60 à 86 400. Elle fixe aussi la durée annoncée dans cache-control. Sans ce paramètre, la durée par défaut du serveur s’applique. Voir Cache. |
Autres paramètres (spécification OpenAPI)
| Paramètre | Type | Défaut | 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. |
Comme pour les captures, les erreurs sont renvoyées en JSON avec le statut HTTP correspondant.
curl -o page.pdf \
"https://omnillink.kayzen-lyon.com/api/v1/pdf?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch&format=Letter&landscape=true"
Extraction
GET/api/v1/extract
Renvoie application/json
Extrait les champs que vous décrivez. fields est un objet JSON, encodé pour une URL, qui associe chaque nom de champ à une règle. La réponse reprend les mêmes noms avec les valeurs extraites.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
string |
Défaut | Adresse absolue de la page, en http ou https, encodée pour une URL. 2 048 caractères au plus, sans identifiants. |
fields obligatoire |
string (JSON) |
Défaut | Objet JSON encodé pour une URL : une règle par champ de sortie, 20 champs au plus. Les propriétés d’une règle sont décrites ci-dessous. |
render |
auto | never | always |
Défautauto |
auto lit la page en HTTP et n’ouvre un navigateur que si le résultat est pauvre. never reste en HTTP. always rend toujours la page dans le navigateur. Voir Rendu. |
force |
boolean |
Défautfalse |
Ignore la lecture du cache et traite de nouveau la page. Le nouveau résultat est tout de même enregistré. |
ttl |
integer |
Défaut | Durée de conservation du résultat dans le cache, en secondes, de 60 à 86 400. Elle fixe aussi la durée annoncée dans cache-control. Sans ce paramètre, la durée par défaut du serveur s’applique. Voir Cache. |
Autres paramètres (spécification OpenAPI)
| Paramètre | Type | Défaut | 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. |
Propriétés d’une règle
| Propriété | Type | Défaut | Description |
|---|---|---|---|
selector obligatoire |
string |
Défaut | Sélecteur CSS de l’élément à lire, 300 caractères au plus. |
attr |
string |
Défauttext |
text pour le texte de l’élément, html pour son contenu HTML, ou le nom d’un attribut comme href, src ou content. |
type |
string |
Défautstring |
Conversion appliquée à la valeur brute : string, number (valeur numérique) ou url (adresse absolue, résolue à partir de celle de la page). |
all |
boolean |
Défautfalse |
Renvoie un tableau de toutes les correspondances, 100 au plus, plutôt que la première seulement. |
Un champ vaut null quand rien ne correspond ou que la valeur ne peut pas être convertie. Les chaînes sont coupées à 10 000 caractères.
/meta, /extract et /content ont besoin d’un document HTML : pour une image, un PDF ou tout autre type de fichier, l’API répond 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
}
}
Contenu
GET/api/v1/content
Renvoie application/json
Renvoie la partie lisible d’une page, sans navigation, publicité ni habillage, en texte brut et en Markdown. Pensé pour les agents IA, le résumé automatique et l’indexation.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
string |
Défaut | Adresse absolue de la page, en http ou https, encodée pour une URL. 2 048 caractères au plus, sans identifiants. |
render |
auto | never | always |
Défautauto |
auto lit la page en HTTP et n’ouvre un navigateur que si le résultat est pauvre. never reste en HTTP. always rend toujours la page dans le navigateur. Voir Rendu. |
force |
boolean |
Défautfalse |
Ignore la lecture du cache et traite de nouveau la page. Le nouveau résultat est tout de même enregistré. |
ttl |
integer |
Défaut | Durée de conservation du résultat dans le cache, en secondes, de 60 à 86 400. Elle fixe aussi la durée annoncée dans cache-control. Sans ce paramètre, la durée par défaut du serveur s’applique. Voir Cache. |
Autres paramètres (spécification OpenAPI)
| Paramètre | Type | Défaut | 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. |
Champs de data
| Champ | Type | Description |
|---|---|---|
url |
string |
Adresse finale, après redirections. |
title |
string | null |
Titre du contenu. |
lang |
string | null |
Langue déclarée par la page. |
excerpt |
string | null |
Court extrait ou description. |
text |
string |
Contenu en texte brut. |
markdown |
string |
Le même contenu en Markdown : titres, listes, liens, code. |
wordCount |
integer |
Nombre de mots du contenu. |
readingTimeMinutes |
integer |
Temps de lecture estimé, en minutes, à 200 mots par minute et arrondi au supérieur. |
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
}
}
Les sections qui suivent, et les tableaux « Autres paramètres », sont générés à partir de la spécification OpenAPI de l’API : leurs descriptions sont en anglais, telles qu’elle les publie.
Metadata of several URLs
POST/api/v1/meta/batch
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
urls obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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).
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
title obligatoire |
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
Renvoie 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…).
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
url obligatoire |
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
Renvoie 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.
Paramètres de requête
| Paramètre | Type | Défaut | Description |
|---|---|---|---|
jsonrpc obligatoire |
string |
||
id |
string |
Omit for a notification (answered with 202, no body). | |
method obligatoire |
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
Renvoie application/json
Renvoie la description OpenAPI 3.1 de l’API, au format JSON. Servez-vous-en pour générer un client typé ou pour l’importer dans votre outil de test d’API.
curl "https://omnillink.kayzen-lyon.com/api/v1/openapi.json"
État du service
GET/health
Renvoie application/json
Renvoie l’état de l’instance : durée de fonctionnement, type de cache utilisé (memory ou redis) et statistiques du pool de navigateurs. Ce point d’accès n’est pas soumis à la limite de débit.
curl "https://omnillink.kayzen-lyon.com/health"
{
"status": "ok",
"uptimeSeconds": 5121,
"cache": "memory",
"browserPool": {
"active": 0,
"queued": 0,
"maxConcurrency": 4,
"browserConnected": true
}
}
Erreurs
Toute erreur a la même forme, quel que soit le point d’accès, y compris ceux qui renvoient une image ou un PDF. Appuyez-vous sur code, qui est stable ; message est destiné aux humains et peut évoluer.
{
"status": "fail",
"code": "EFORBIDDENURL",
"message": "Destination is not allowed"
}
| Code | HTTP | status | Signification |
|---|---|---|---|
EINVALIDPARAMS |
HTTP400 | fail |
Un paramètre est manquant, inconnu ou invalide. Ce code accompagne aussi le statut 404 d’une route inexistante. |
EINVALIDURL |
HTTP400 | fail |
L’url est mal formée ou n’utilise ni http ni https. |
EUNAUTHORIZED |
HTTP401 | fail |
La clé envoyée dans x-api-key est inconnue. |
EFORBIDDENURL |
HTTP403 | fail |
La destination est refusée par la politique anti-SSRF : adresse privée, de bouclage ou de métadonnées, nom d’hôte interne, ou port non autorisé. |
EEMBEDNOTFOUND |
HTTP404 | fail |
Le chemin demandé avec embed est absent de la réponse /meta, ou vaut null. |
ESELECTORNOTFOUND |
HTTP404 | fail |
Le selector passé à /screenshot ne correspond à aucun élément visible. |
ENOTHTML |
HTTP422 | fail |
La cible n’est pas un document HTML, alors que ce point d’accès en a besoin. |
ETOOLARGE |
HTTP422 | fail |
Le résultat généré dépasse la taille maximale autorisée. |
ERATELIMIT |
HTTP429 | fail |
Trop de requêtes. Attendez le délai indiqué dans le message et dans l’en-tête retry-after. |
EBROWSER |
HTTP500 | error |
Le navigateur sans interface a planté ou n’a pas pu démarrer. |
EINTERNAL |
HTTP500 | error |
Erreur inattendue du serveur. Aucun détail interne n’est divulgué. |
EUNREACHABLE |
HTTP502 | error |
La cible est injoignable : échec DNS, connexion refusée, erreur TLS. |
ETARGETSTATUS |
HTTP502 | error |
La cible a répondu avec un statut HTTP d’erreur. |
EBLOCKED |
HTTP502 | error |
La cible a répondu par une page de blocage anti-robot au lieu de son contenu. Cette réponse n’est jamais mise en cache. |
EBUSY |
HTTP503 | error |
La file de rendu est pleine. Réessayez dans un instant. |
ECIRCUITOPEN |
HTTP503 | error |
La cible a échoué plusieurs fois de suite : elle n’est plus contactée pendant un court délai. |
ETIMEOUT |
HTTP504 | error |
La cible n’a pas répondu à temps. |
Modèle de sécurité
Une API qui visite des adresses fournies par ses utilisateurs est une cible classique d’attaques SSRF. Omnillink valide chaque destination avant de s’y connecter.
- Seuls
httpethttpssont acceptés, sans identifiants dans l’adresse, et sur une liste de ports autorisés (80 et 443 par défaut). localhost, les noms internes et toute adresse non routable publiquement sont refusés : plages privées, bouclage, lien local dont169.254.169.254, CGNAT, IPv6 ULA, adresses IPv4 mappées. Les notations inhabituelles comme0x7f.1sont normalisées avant le contrôle.- Un seul enregistrement DNS privé suffit à faire refuser un nom d’hôte.
- En HTTP, la résolution DNS validée est épinglée à la connexion, et chaque redirection est revalidée.
- Dans le navigateur, deux couches. Chaque requête émise par la page est interceptée et validée ; WebSockets et service workers sont coupés. Et Chromium n’a pour seule sortie réseau qu’un proxy interne à l’API : à chaque connexion, redirections comprises, ce proxy applique la politique, résout le nom lui-même et se connecte à l’adresse qu’il vient de valider.
Ce qui n’est pas couvert : ce proxy vit dans le même processus que l’API. Il ne remplace pas un filtrage de sortie au niveau du réseau (pare-feu, VPC), qui reste recommandé en défense en profondeur. La protection porte sur les destinations que le navigateur peut joindre, pas sur ce que fait une page une fois chargée. Le README du dépôt donne le détail.