Sur cette page

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.

Bac à sableopenapi.json

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.

Requête
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.

Requête
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êteDescription
x-ratelimit-limitNombre de requêtes autorisées dans la fenêtre.
x-ratelimit-remainingNombre de requêtes restantes dans la fenêtre en cours.
x-ratelimit-resetSecondes avant la remise à zéro de la fenêtre.
retry-afterPré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.

Réponse
{
  "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.

Réponse
{
  "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ètreTypeDéfautDescription
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.
Requête
curl "https://omnillink.kayzen-lyon.com/api/v1/meta?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"
Réponse
{
  "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
  }
}
Un champ utilisé comme image
<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ètreTypeDéfautDescription
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.

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

PDF

GET/api/v1/pdf

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ètreTypeDéfautDescription
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.

Requête
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ètreTypeDéfautDescription
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).

Règles
{
  "price": {
    "selector": ".price",
    "attr": "text",
    "type": "number"
  },
  "links": {
    "selector": "a",
    "attr": "href",
    "type": "url",
    "all": true
  }
}
Requête
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}}'
Réponse
{
  "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ètreTypeDéfautDescription
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.
Requête
curl "https://omnillink.kayzen-lyon.com/api/v1/content?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"
Réponse
{
  "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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
curl "https://omnillink.kayzen-lyon.com/api/v1/tables?url=https%3A%2F%2Fexample.com%2Fblog%2Flaunch"

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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
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.
Requête
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ètreTypeDéfautDescription
url obligatoire string Absolute http(s) URL of the target page.
Requête
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ètreTypeDéfautDescription
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": { … } }.
Requête
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.

Requête
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.

Requête
curl "https://omnillink.kayzen-lyon.com/health"
Réponse
{
  "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.

Réponse
{
  "status": "fail",
  "code": "EFORBIDDENURL",
  "message": "Destination is not allowed"
}
CodeHTTPstatusSignification
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 http et https sont 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 dont 169.254.169.254, CGNAT, IPv6 ULA, adresses IPv4 mappées. Les notations inhabituelles comme 0x7f.1 sont 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.

Raccourcis clavier

CtrlKou/
Ouvrir la recherche et les commandes
?
Afficher cette aide
←→
Passer d’un onglet à l’autre
Ctrl↵
Lancer la requête dans le bac à sable
Esc
Fermer un panneau ou un menu

Les raccourcis à une seule touche se désactivent dans les options d’accessibilité.