Todo es un Objeto
Cada recurso en Olostep es un objeto con un identificador único. Ya sea que lo crees a través de la API, SDK o el panel de control, obtienes un objeto que puedes referenciar, actualizar y consultar.Rutas singulares / API orientada a acciones
Aunque siempre estamos dispuestos a luchar arduamente por la pureza ideológica del diseño de API orientada a objetos (un POST en/crawls debería crear un objeto crawl, mientras que un GET en /crawls/{crawl_id} debería ayudarte a recuperar ese objeto y posiblemente actualizarlo — siempre puedes actualizar metadatos),
cada colección también responde a su nombre singular: POST /v1/answer se comporta exactamente como POST /v1/answers, GET /v1/scrape/{scrape_id} como GET /v1/scrapes/{scrape_id}, y así sucesivamente para batch, crawl, map, search, schedule, monitor, file y feedback.
El plural es la forma canónica y la que documenta esta referencia; el singular es un alias para cuando piensas en acciones en lugar de objetos.
Los Objetos Pueden Tener Ciclos de Vida
Algunos objetos de Olostep rastrean el estado a través de un campostatus. Este patrón de máquina de estados te permite saber exactamente en qué parte de su ciclo de vida se encuentra cada recurso.
Batches
Los batches tienen dos niveles de estado: el batch en sí y los elementos individuales. Estado del Batch:Las fallas a nivel de batch son extremadamente raras. Los batches casi siempre se completan, incluso si algunas URLs fallan, el batch en sí alcanza el estado
completed. En el raro caso de una falla catastrófica de infraestructura (por ejemplo, interrupción del servicio LLM durante el enriquecimiento), el batch puede fallar. Esto afecta a menos del 0.01% de los batches.
Los elementos pueden fallar debido a:
- La URL está bloqueada o devuelve un error
- Falta la salida del analizador
- Errores de red/obtención
error con code y message explicando la falla. El batch aún se completa: verifica el estado de cada elemento al procesar los resultados.
Crawls
Los crawls siempre se completan. Incluso si un crawl encuentra 0 URLs (debido a bloqueo de robots.txt o URL de inicio inválida), el estado del crawl será
completed. Verifica el campo pages_count para verificar los resultados.Monitors
Los monitores son objetos de larga duración con un ciclo de vida más rico que los recursos de una sola vez:
Crear un monitor devuelve HTTP
202 con status: provisioning. El monitor se vuelve active una vez que la planificación resuelve sus objetivos rastreados — consulta GET /v1/monitors/:monitor_id o transmite eventos de provisión con ?stream=1. Solo los monitores active pueden ser pausados, y solo los monitores paused pueden ser reanudados. Las actualizaciones devuelven 409 mientras el monitor aún está provisioning.
Patrón de Recuperación
Muchos objetos producen contenido que puede ser recuperado más tarde. El patrónretrieve_id te permite obtener contenido sin volver a procesarlo.
- Elementos del batch — Cada URL procesada obtiene un
retrieve_id - Páginas de crawl — Cada página rastreada obtiene un
retrieve_id
/v1/retrieve acepta el parámetro formats para especificar qué tipos de contenido devolver (html, markdown, json, text).