> ## 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 Orientata agli Oggetti

> Comprendere come funzionano insieme gli oggetti dell’API Olostep

L'API di Olostep è progettata attorno agli oggetti. Comprendere questo design ti aiuta a costruire integrazioni più efficaci.

***

## Tutto è un Oggetto

Ogni risorsa in Olostep è un oggetto con un identificatore unico. Che tu lo crei tramite l'API, l'SDK o la dashboard — ottieni un oggetto che puoi referenziare, aggiornare e interrogare.

| Risorsa  | Formato ID Oggetto | Esempio           |
| -------- | ------------------ | ----------------- |
| 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` |

***

## Gli Oggetti Possono Avere Cicli di Vita

Alcuni oggetti di Olostep tracciano lo stato attraverso un campo `status`. Questo schema a macchina a stati ti permette di sapere esattamente dove si trova ogni risorsa nel suo ciclo di vita.

### Batch

I batch hanno due livelli di stato: il **batch** stesso e i singoli **elementi**.

**Stato del Batch:**

```
in_progress → completed
```

| Stato         | Descrizione                      |
| ------------- | -------------------------------- |
| `in_progress` | Gli URL sono in fase di scraping |
| `completed`   | Elaborazione terminata           |

<Note>
  **I fallimenti a livello di batch sono estremamente rari.** I batch quasi sempre si completano — anche se alcuni URL falliscono, il batch stesso raggiunge lo stato `completed`. Nel raro caso di un fallimento catastrofico dell'infrastruttura (ad esempio, interruzione del servizio LLM durante l'arricchimento), il batch potrebbe fallire. Questo riguarda meno dello 0,01% dei batch.
</Note>

**Stato dell'Elemento:**

Ogni URL in un batch è tracciato come un elemento individuale con il proprio stato:

| Stato     | Descrizione                 |
| --------- | --------------------------- |
| `success` | URL scrappato con successo  |
| `failed`  | Impossibile scrappare l'URL |

Gli elementi possono fallire a causa di:

* URL bloccato o che restituisce un errore
* Output del parser mancante
* Errori di rete/fetch

Gli elementi falliti includono un oggetto `error` con `code` e `message` che spiegano il fallimento. Il batch si completa comunque — controlla lo stato di ciascun elemento quando elabori i risultati.

### Crawl

```
in_progress → completed
```

| Stato         | Descrizione                              |
| ------------- | ---------------------------------------- |
| `in_progress` | Scoperta e elaborazione attiva degli URL |
| `completed`   | Crawling terminato                       |

<Note>
  **I crawl si completano sempre.** Anche se un crawl trova 0 URL (a causa del blocco di robots.txt o URL di partenza non valido), lo stato del crawl sarà `completed`. Controlla il campo `pages_count` per verificare i risultati.
</Note>

### Monitor

I monitor sono oggetti di lunga durata con un ciclo di vita più ricco rispetto alle risorse one-shot:

```
provisioning → active ⇄ paused
            ↘ failed
```

| Stato          | Descrizione                                                                                 |
| -------------- | ------------------------------------------------------------------------------------------- |
| `provisioning` | Agente, specifica, pianificatore e programma sono in fase di configurazione                 |
| `active`       | Programma abilitato; le esecuzioni avvengono su `schedule.frequency`                        |
| `paused`       | Programma disabilitato tramite `POST /v1/monitors/:monitor_id/pause`                        |
| `failed`       | Fallimento della configurazione o aggiornamento del programma (`error_message` è impostato) |
| `deleted`      | Eliminato in modo soft tramite `DELETE /v1/monitors/:monitor_id`                            |

Creare un monitor restituisce HTTP `202` con `status: provisioning`. Il monitor diventa `active` una volta che la pianificazione risolve i suoi obiettivi tracciati — interroga `GET /v1/monitors/:monitor_id` o trasmetti eventi di provisioning con `?stream=1`. Solo i monitor `active` possono essere messi in pausa, e solo i monitor `paused` possono essere ripresi. Gli aggiornamenti restituiscono `409` mentre il monitor è ancora in `provisioning`.

***

## Pattern di Recupero

Molti oggetti producono contenuti che possono essere recuperati successivamente. Il pattern `retrieve_id` ti permette di recuperare contenuti senza ri-elaborarli.

```bash theme={null}
# Ottieni contenuto usando retrieve_id
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
  -H "Authorization: Bearer <your_token>"
```

Questo pattern è utilizzato da:

* **Elementi del batch** — Ogni URL elaborato ottiene un `retrieve_id`
* **Pagine del crawl** — Ogni pagina scrappata ottiene un `retrieve_id`

L'endpoint `/v1/retrieve` accetta il parametro `formats` per specificare quali tipi di contenuto restituire (`html`, `markdown`, `json`, `text`).

***

## Webhook: Aggiornamenti Basati su Eventi

Invece di interrogare per i cambiamenti di stato, configura i [webhook](/api-reference/common/webhooks) per ricevere eventi quando gli oggetti cambiano stato.

```json theme={null}
{
  "event": "batch.completed",
  "data": {
    "id": "batch_xyz789",
    "status": "completed",
    "items_total": 100,
    "items_completed": 100
  }
}
```

***

## Metadata: I Tuoi Dati Accanto ai Nostri

Allega coppie chiave-valore personalizzate agli oggetti usando i [metadata](/api-reference/common/metadata). Questo ti permette di collegare le risorse di Olostep ai tuoi sistemi interni.

```json theme={null}
{
  "items": [{"url": "https://example.com"}],
  "metadata": {
    "order_id": "12345",
    "customer": "acme-corp"
  }
}
```

***

## Riepilogo

| Concetto          | Descrizione                                          |
| ----------------- | ---------------------------------------------------- |
| **Oggetti**       | Ogni risorsa ha un ID unico ed è interrogabile       |
| **Cicli di Vita** | Traccia il progresso tramite il campo `status`       |
| **Recupero**      | Recupera contenuti successivamente con `retrieve_id` |
| **Webhook**       | Ricevi notifiche quando lo stato cambia              |
| **Metadata**      | Allega i tuoi dati a qualsiasi oggetto               |