Skip to main content
La API de Olostep está diseñada en torno a objetos. Comprender este diseño te ayuda a construir integraciones más efectivas.

​
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 panel de control, obtienes un objeto que puedes referenciar, actualizar y consultar.

​
Los Objetos Pueden Tener Ciclos de Vida

Algunos objetos de Olostep rastrean el estado a través de un campo status. Este patrón de máquina de estados te permite saber exactamente en qué parte del ciclo de vida se encuentra cada recurso.

​
Batches

Los batches tienen dos niveles de estado: el batch en sí y los items 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, una interrupción del servicio LLM durante el enriquecimiento), el batch puede fallar. Esto afecta a menos del 0.01% de los batches.
Estado del Item: Cada URL en un batch se rastrea como un item individual con su propio estado: Los items pueden fallar debido a:
  • La URL está bloqueada o devuelve un error
  • Falta la salida del parser
  • Errores de red/fetch
Los items fallidos incluyen un objeto error con code y message explicando la falla. El batch aún se completa: verifica el estado de cada item al procesar los resultados.

​
Crawls

Los crawls siempre se completan. Incluso si un crawl encuentra 0 URLs (debido al bloqueo de robots.txt o URL de inicio inválida), el estado del crawl será completed. Verifica el campo pages_count para confirmar 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 recuperarse más tarde. El patrón retrieve_id te permite obtener contenido sin volver a procesarlo.
Este patrón es utilizado por:
  • Items de batch — Cada URL procesada obtiene un retrieve_id
  • Páginas de crawl — Cada página rastreada obtiene un retrieve_id
El endpoint /v1/retrieve acepta el parámetro formats para especificar qué tipos de contenido devolver (html, markdown, json, text).

​
Webhooks: Actualizaciones Basadas en Eventos

En lugar de consultar cambios de estado, configura webhooks para recibir eventos cuando los objetos cambian de estado.

​
Metadata: Tus Datos Junto a los Nuestros

Adjunta pares clave-valor personalizados a los objetos usando metadata. Esto te permite vincular recursos de Olostep a tus sistemas internos.

​
Resumen