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:
| Stato | Descrizione |
|---|
in_progress | Gli URL sono in fase di scraping |
completed | Elaborazione terminata |
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.
| Stato | Descrizione |
|---|
success | URL scrappato con successo |
failed | Impossibile scrappare l’URL |
- 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
| Stato | Descrizione |
|---|
in_progress | Scoperta e elaborazione attiva degli URL |
completed | Crawling terminato |
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.
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 |
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.
# Ottieni contenuto usando retrieve_id
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
-H "Authorization: Bearer <your_token>"
- 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 per ricevere eventi quando gli oggetti cambiano stato.
{
"event": "batch.completed",
"data": {
"id": "batch_xyz789",
"status": "completed",
"items_total": 100,
"items_completed": 100
}
}
Allega coppie chiave-valore personalizzate agli oggetti usando i metadata. Questo ti permette di collegare le risorse di Olostep ai tuoi sistemi interni.
{
"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 |
