Skip to main content
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.

​
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:
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 dell’Elemento: Ogni URL in un batch è tracciato come un elemento individuale con il proprio stato: 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

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:
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.
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 per ricevere eventi quando gli oggetti cambiano stato.

​
Metadata: I Tuoi Dati Accanto ai Nostri

Allega coppie chiave-valore personalizzate agli oggetti usando i metadata. Questo ti permette di collegare le risorse di Olostep ai tuoi sistemi interni.