L’API d’Olostep est conçue autour des objets. Comprendre ce design vous aide à créer des intégrations plus efficaces.
Tout est un Objet
Chaque ressource dans Olostep est un objet avec un identifiant unique. Que vous le créiez via l’API, le SDK ou le tableau de bord — vous recevez un objet que vous pouvez référencer, mettre à jour et interroger.
| Ressource | Format de l’ID d’Objet | Exemple |
|---|
| Scrape | scrape_* | scrape_abc123 |
| Batch | batch_* | batch_xyz789 |
| Crawl | crawl_* | crawl_def456 |
| Map | map_* | map_ghi012 |
| Answer | answer_* | answer_jkl345 |
| Search | search_* | search_mno678 |
| Monitor | monitor_* | monitor_mno678 |
| File | file_* | file_mno678 |
| Schedule | schedule_* | schedule_pqr901 |
Les Objets Peuvent Avoir des Cycles de Vie
Certains objets Olostep suivent un état via un champ status. Ce modèle de machine à états vous permet de savoir exactement où se trouve chaque ressource dans son cycle de vie.
Batches
Les batches ont deux niveaux de statut : le batch lui-même et les éléments individuels.
Statut du Batch :
| Statut | Description |
|---|
in_progress | Les URL sont en cours de scraping |
completed | Traitement terminé |
Les échecs au niveau du batch sont extrêmement rares. Les batches se terminent presque toujours — même si certaines URL échouent, le batch lui-même atteint le statut completed. Dans le cas rare d’une défaillance catastrophique de l’infrastructure (par exemple, une panne du service LLM pendant l’enrichissement), le batch peut échouer. Cela affecte moins de 0,01% des batches.
| Statut | Description |
|---|
success | URL scrappée avec succès |
failed | URL n’a pas pu être scrappée |
- L’URL est bloquée ou retourne une erreur
- Sortie du parseur manquante
- Erreurs de réseau/récupération
Les éléments échoués incluent un objet error avec code et message expliquant l’échec. Le batch se termine toujours — vérifiez le statut de chaque élément lors du traitement des résultats.
Crawls
| Statut | Description |
|---|
in_progress | Découverte et traitement actifs des URL |
completed | Crawling terminé |
Les crawls se terminent toujours. Même si un crawl ne trouve aucune URL (en raison du blocage par robots.txt ou d’une URL de départ invalide), le statut du crawl sera completed. Vérifiez le champ pages_count pour vérifier les résultats.
Monitors
Les monitors sont des objets de longue durée avec un cycle de vie plus riche que les ressources ponctuelles :
provisioning → active ⇄ paused
↘ failed
| Statut | Description |
|---|
provisioning | Agent, spécification, planificateur et calendrier sont en cours de configuration |
active | Calendrier activé ; les exécutions se font selon schedule.frequency |
paused | Calendrier désactivé via POST /v1/monitors/:monitor_id/pause |
failed | Échec de la configuration ou de la mise à jour du calendrier (error_message est défini) |
deleted | Suppression logique via DELETE /v1/monitors/:monitor_id |
202 avec status: provisioning. Le monitor devient active une fois que la planification résout ses cibles suivies — interrogez GET /v1/monitors/:monitor_id ou diffusez les événements de provisionnement avec ?stream=1. Seuls les monitors active peuvent être mis en pause, et seuls les monitors paused peuvent être repris. Les mises à jour retournent 409 tant que le monitor est encore en provisioning.
Modèle de Récupération
De nombreux objets produisent du contenu qui peut être récupéré plus tard. Le modèle retrieve_id vous permet de récupérer du contenu sans le retraiter.
# Obtenez du contenu en utilisant retrieve_id
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
-H "Authorization: Bearer <your_token>"
- Éléments de batch — Chaque URL traitée obtient un
retrieve_id
- Pages de crawl — Chaque page crawlée obtient un
retrieve_id
Le point de terminaison /v1/retrieve accepte le paramètre formats pour spécifier quels types de contenu retourner (html, markdown, json, text).
Webhooks : Mises à Jour Événementielles
Au lieu de sonder pour les changements de statut, configurez des webhooks pour recevoir des événements lorsque les objets changent d’état.
{
"event": "batch.completed",
"data": {
"id": "batch_xyz789",
"status": "completed",
"items_total": 100,
"items_completed": 100
}
}
Métadonnées : Vos Données à Côté des Nôtres
Attachez des paires clé-valeur personnalisées aux objets en utilisant les métadonnées. Cela vous permet de lier les ressources Olostep à vos systèmes internes.
{
"items": [{"url": "https://example.com"}],
"metadata": {
"order_id": "12345",
"customer": "acme-corp"
}
}
Résumé
| Concept | Description |
|---|
| Objets | Chaque ressource a un ID unique et est interrogeable |
| Cycles de Vie | Suivez la progression via le champ status |
| Récupération | Récupérez le contenu plus tard avec retrieve_id |
| Webhooks | Soyez notifié lorsque l’état change |
| Métadonnées | Attachez vos propres données à n’importe quel objet |
