> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API Orientée Objet

> Comprendre comment les objets de l’API Olostep fonctionnent ensemble

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 :**

```
in_progress → completed
```

| Statut        | Description                       |
| ------------- | --------------------------------- |
| `in_progress` | Les URL sont en cours de scraping |
| `completed`   | Traitement terminé                |

<Note>
  **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.
</Note>

**Statut de l'Élément :**

Chaque URL dans un batch est suivie comme un élément individuel avec son propre statut :

| Statut    | Description                  |
| --------- | ---------------------------- |
| `success` | URL scrappée avec succès     |
| `failed`  | URL n'a pas pu être scrappée |

Les éléments peuvent échouer pour les raisons suivantes :

* 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

```
in_progress → completed
```

| Statut        | Description                             |
| ------------- | --------------------------------------- |
| `in_progress` | Découverte et traitement actifs des URL |
| `completed`   | Crawling terminé                        |

<Note>
  **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.
</Note>

### 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`                                 |

La création d'un monitor retourne HTTP `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.

```bash theme={null}
# Obtenez du contenu en utilisant retrieve_id
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
  -H "Authorization: Bearer <your_token>"
```

Ce modèle est utilisé par :

* **É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](/api-reference/common/webhooks) pour recevoir des événements lorsque les objets changent d'état.

```json theme={null}
{
  "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](/api-reference/common/metadata). Cela vous permet de lier les ressources Olostep à vos systèmes internes.

```json theme={null}
{
  "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  |