API : endpoints et exemples d’utilisation

1. Choisir entre API et MCP

Un endpoint est une adresse qui réalise une opération précise : extraire les URL d’un sitemap, lire les performances Search Console ou lancer un crawl. Vous envoyez une requête HTTP et récupérez une réponse exploitable dans votre script ou votre outil d’automatisation.

Ce guide présente les endpoints des outils API. Il ne constitue pas la liste des routes internes du SaaS ni celle des outils du MCP. La vue Google Analytics du SaaS ne doit pas non plus être confondue avec l’endpoint Search Console ci-dessous.

2. Préparer la connexion

L’adresse de base est https://api.cuik.io. Envoyez votre clé Cuik dans l’en-tête Authorization, sans Bearer, et un corps JSON pour les requêtes POST.

Le guide Authentification et première requête montre où récupérer la clé et comment faire une première lecture sans lancer d’audit.

Pour les exemples Bash de cette page, saisissez la clé une seule fois, sans l’afficher :

read -r -s -p "Clé API Cuik : " CUIK_API_KEY
export CUIK_API_KEY

Les appels d’extraction et d’analyse utilisent votre compte réel et peuvent consommer des crédits. Vérifiez le coût et les options dans la fiche API correspondante avant de lancer une boucle. Copier un exemple ne l’exécute pas.

Recherche Google : ajoutez "pages": 3 pour demander trois pages de dix résultats maximum, soit 3 crédits. La consultation de Search Console dans l’interface Cuik ne consomme pas ces crédits ; l’extraction via /v1/search_console coûte 1 crédit par appel.

3. Trouver le bon endpoint

Filtres, valeurs par défaut, pagination et exemple PHP : lire et exporter les liens d’un crawl.

/search n’a pas le préfixe /v1. Ne le rajoutez pas. Les paramètres géographiques ne sont pas interchangeables non plus : gl: "fr" pour la recherche, location_code: 2250 pour les mots-clés positionnés, par exemple. Utilisez le générateur de l’outil pour choisir les bonnes valeurs.

Ouvrir les fiches interactives : sitemap, extraction de page, recherche, PageSpeed, captures, Search Console, mots-clés, backlinks et crawl.

4. Trois premières requêtes

Extraire les URL d’un site

Remplacez https://example.com par le site à examiner.

curl --fail-with-body --silent --show-error \
  --max-time 120 \
  'https://api.cuik.io/v1/sitemap/urls' \
  -H "Authorization: $CUIK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"site":"https://example.com"}'

La réponse contient urls, count, domain, status et éventuellement error_message. Vérifiez aussi status : une réponse HTTP reçue correctement peut indiquer qu’aucun sitemap exploitable n’a été trouvé.

Un sitemap contient des URL déclarées par le site. Ce n’est ni la preuve qu’elles sont indexées dans Google, ni la liste garantie de toutes les pages existantes.

Observer une recherche Google

curl --fail-with-body --silent --show-error \
  --max-time 120 \
  'https://api.cuik.io/search' \
  -H "Authorization: $CUIK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"q":"logiciel reporting SEO","gl":"fr","hl":"fr","num":10,"page":1}'

Vous demandez ici la première page de résultats, en français pour la France. Selon le type de recherche et les résultats disponibles, les sections de réponse varient ; les résultats naturels se trouvent généralement dans organic.

Conservez la requête, le pays, la langue et la date avec la réponse si vous souhaitez comparer plusieurs relevés. Une requête isolée n’installe pas un suivi de positions récurrent : votre script planifie et conserve les observations.

Lire les performances Search Console

La propriété doit être connectée à votre compte Cuik. Pour cet endpoint de production, indiquez https://example.com pour une propriété de domaine sc-domain:example.com, ou l’URL de la propriété avec préfixe. Le format sc-domain: utilisé par d’autres outils Cuik n’est pas accepté par toutes les versions de cet endpoint.

curl --fail-with-body --silent --show-error \
  --max-time 120 \
  'https://api.cuik.io/v1/search_console' \
  -H "Authorization: $CUIK_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"property_url":"https://example.com","startDate":"2026-08-01","endDate":"2026-08-31","dimensions":["page"],"searchType":"web","rowLimit":1000}'

Adaptez les dates à une période disponible. Ici, le résultat est regroupé par page. Avec dimensions: ["query"], vous analysez les requêtes ; avec ["date"], leur évolution quotidienne. Les ventilations n’ont pas toutes le même périmètre de restitution : ne supposez pas que la somme des requêtes reproduit exactement un total par propriété.

rowLimit limite la taille du lot. L’endpoint accepte aussi startRow pour demander les lots suivants ; un premier lot ne prouve pas que vous avez récupéré toutes les lignes disponibles. La réponse ne donne pas un inventaire exhaustif des pages indexées.

5. Automatiser un petit audit de performance

Ce script Python 3 analyse deux URL maximum, successivement, sur mobile. Remplacez les deux URL, installez requests (python -m pip install requests) et utilisez la variable CUIK_API_KEY préparée plus haut.

import json
import os
from datetime import datetime, timezone
from pathlib import Path

import requests

urls = ["https://example.com/", "https://example.com/services/"]
output = Path("cuik-pagespeed")
output.mkdir(exist_ok=True)
stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")

with requests.Session() as client:
    client.headers.update({"Authorization": os.environ["CUIK_API_KEY"]})
    for index, url in enumerate(urls[:2], start=1):
        response = client.post(
            "https://api.cuik.io/v1/pagespeed",
            json={"url": url, "strategy": "mobile"},
            timeout=120,
        )
        response.raise_for_status()
        result = {"url": url, "strategy": "mobile", "data": response.json()}
        target = output / f"{stamp}-{index}.json"
        target.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
        print(f"Résultat enregistré : {target}")

Chaque analyse est une requête distincte. Pour desktop, utilisez strategy: "desktop" dans un appel séparé. Un score de laboratoire peut varier entre deux exécutions ; conservez les conditions de mesure avec le résultat.

Le script s’arrête en cas d’erreur HTTP. Il n’essaie pas automatiquement de relancer une analyse qui pourrait avoir déjà consommé des crédits.

6. Construire un usage concret

Dans n8n ou Make, partez d’un module HTTP : méthode et URL du tableau, clé dans les identifiants sécurisés, corps JSON puis stockage de la réponse. Le déclenchement récurrent et l’historique sont gérés par votre scénario.

Pour un crawl, le lancement et le résultat sont séparés : gardez le crawl_id, puis consultez son état au lieu de relancer un nouvel audit. Le guide Lancer et suivre un crawl détaille ce parcours et les réponses.

7. Comprendre les erreurs et les limites

• 401 : vérifiez la clé et son en-tête, notamment l’absence de Bearer avec une clé sk_.
• 403 : lisez le message : droits insuffisants ou crédits indisponibles selon l’opération.
• 404 : vérifiez le chemin et l’identifiant demandé.
• 422 : corrigez les champs indiqués dans la réponse : nom, type ou format.
• 429 : respectez le délai indiqué avant une nouvelle tentative, s’il est fourni.
• Délai dépassé / erreur serveur : une absence de réponse n’établit pas que l’opération n’a pas démarré. Vérifiez l’état disponible avant de répéter une action payante.

Pour demander de l’aide, gardez le chemin appelé, l’heure, les paramètres utiles et le message d’erreur, sans transmettre la clé API. Les limites de collecte, de crédits et d’accès aux sources continuent de s’appliquer lorsqu’un appel vient d’un script.