Automatiser vos crawls avec l’API
Un workflow planifié, le suivi des états et les précautions contre les audits en double.
Dans ce guide
Choisir une fréquence utile
Une automatisation peut vérifier un site après une mise en ligne ou préparer un audit périodique. Commencez avec une fréquence faible, par exemple un audit hebdomadaire. Chaque lancement utilise le quota d’audits du compte, même lorsqu’il provient de votre propre script ou d’un assistant MCP. Un workflow planifié ne dispense pas de vérifier le périmètre et la capacité disponibles.
Ce guide décrit un workflow à configurer dans votre outil d’automatisation ou votre script ; il ne décrit pas un planificateur intégré à Cuik. Avant de le programmer, faites un lancement manuel via le guide API du crawl.
1. Préparer la requête de lancement
Conservez la clé dans le gestionnaire de secrets de votre outil. N’exposez pas une clé Cuik dans une page web publique ou un dépôt Git. L’authentification API précise le format de l’en-tête.
| Réglage du workflow | Valeur |
|---|---|
| Méthode | POST |
| Adresse | https://api.cuik.io/v1/crawl |
| En-tête | Authorization: <votre clé Cuik> |
| Type de contenu | application/json |
| Relance automatique du POST | Désactivée |
Voici un premier corps JSON limité à 100 URL, sans documents :
{
"url": "https://example.com/",
"engine": "legacy",
"max_urls": 100,
"urls_per_second": 2,
"js": false,
"sheet": false,
"slide": false
}Remplacez le domaine. legacy désigne le moteur Classique ; cuikspider suppose que la bêta soit accessible sur l’environnement utilisé. Pour une analyse régulière, gardez la même configuration d’une exécution à l’autre afin de comparer un périmètre similaire.
2. Construire le workflow
| Étape | Action | Donnée à conserver |
|---|---|---|
| Déclenchement | Horloge hebdomadaire ou événement de mise en ligne. | Site, date et identifiant de votre exécution. |
| Garde-fou | Vérifier qu’aucune exécution précédente de ce workflow n’est encore active ou de statut incertain. | Le journal persistant du workflow. |
| Lancement | Envoyer une seule requête POST. | Le champ id de la réponse, immédiatement. |
| Attente | Attendre au moins 10 secondes. | Le même id. |
| Suivi | Appeler GET https://api.cuik.io/v1/crawl/{id} avec le même en-tête. |
L’objet crawl et son dernier état. |
| Décision | Continuer à attendre, finir ou vous alerter selon l’état. | Lien du résultat et éventuel message d’erreur. |
La donnée persistante est importante : si votre outil redémarre, il doit reprendre le suivi du même crawl, pas créer un second audit. Limitez aussi la durée totale d’attente, par exemple à une heure pour un petit test. À expiration de ce délai, envoyez une alerte avec l’identifiant ; ne déclenchez pas un nouveau POST.
3. Traiter les états sans perdre le résultat
Le lancement renvoie id directement, alors que le suivi renvoie un objet crawl. Lisez crawl.status, crawl.crawl_status lorsqu’il est présent, les compteurs et le message d’erreur. Ces deux appels n’ont pas le même format.
- En attente, en cours ou en finalisation : temporisez, puis relisez l’état.
- Collecte réussie : récupérez le résultat disponible ; les documents peuvent encore être en préparation.
- Erreur, interruption, arrêt ou pause : conservez le crawl et son message, puis alertez la personne responsable au lieu de boucler indéfiniment.
- État nouveau ou non reconnu : gardez l’identifiant et signalez-le ; ne l’interprétez pas comme une réussite.
Si vous demandez des Sheets/Slides, le succès de la collecte ne suffit pas à garantir que les deux documents sont prêts. Contrôlez leurs liens disponibles séparément. Vous pouvez aussi les générer ensuite depuis l’audit dans l’application.
4. Éviter les audits en double
Un timeout du POST signifie que votre outil n’a pas reçu la réponse. Il ne prouve pas que Cuik n’a pas lancé l’audit. En cas de coupure, consultez GET /v1/crawls et retrouvez le site et l’heure concernés avant toute nouvelle tentative. Parcourez les pages si nécessaire ; ne prenez pas le premier résultat du compte sans vérifier son site.
N’ajoutez pas un en-tête d’idempotence arbitraire en supposant qu’il évitera les doublons : ce contrat n’est pas garanti par cet endpoint. La protection consiste ici à enregistrer votre lancement, à garder son identifiant et à bloquer les relances dont le résultat est incertain.
5. Recetter avant de planifier
Testez un petit site, un refus d’accès et une interruption de votre propre workflow après réception de l’identifiant. Vérifiez qu’il reprend le même crawl, qu’il s’arrête sur une erreur et que votre alerte contient le bon lien ou identifiant.
Gardez vos alertes dans un seul canal. Pour les problèmes d’IP, robots.txt, quotas externes ou documents, consultez le guide de dépannage. Pour lancer une analyse avec un assistant, utilisez le connecteur MCP ; une conversation seule n’est pas un planificateur récurrent.