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.
| Recurso | Formato de ID de Objeto | Ejemplo |
|---|
| 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 |
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:
| Estado | Descripción |
|---|
in_progress | Las URLs están siendo scrapeadas |
completed | Procesamiento finalizado |
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 | Descripción |
|---|
success | URL scrapeada con éxito |
failed | No se pudo scrapear la URL |
- 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
| Estado | Descripción |
|---|
in_progress | Descubriendo y procesando URLs activamente |
completed | Crawling finalizado |
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:
provisioning → active ⇄ paused
↘ failed
| Estado | Descripción |
|---|
provisioning | Se están configurando el agente, especificación, planificador y horario |
active | Horario habilitado; las ejecuciones se realizan en schedule.frequency |
paused | Horario deshabilitado a través de POST /v1/monitors/:monitor_id/pause |
failed | Falló la provisión o actualización del horario (error_message está establecido) |
deleted | Borrado suave a través de DELETE /v1/monitors/:monitor_id |
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.
# Obtener contenido usando retrieve_id
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
-H "Authorization: Bearer <your_token>"
- 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.
{
"event": "batch.completed",
"data": {
"id": "batch_xyz789",
"status": "completed",
"items_total": 100,
"items_completed": 100
}
}
Adjunta pares clave-valor personalizados a los objetos usando metadata. Esto te permite vincular recursos de Olostep a tus sistemas internos.
{
"items": [{"url": "https://example.com"}],
"metadata": {
"order_id": "12345",
"customer": "acme-corp"
}
}
Resumen
| Concepto | Descripción |
|---|
| Objetos | Cada recurso tiene un ID único y es consultable |
| Ciclos de Vida | Rastrear el progreso a través del campo status |
| Recuperar | Obtener contenido más tarde con retrieve_id |
| Webhooks | Recibir notificaciones cuando cambia el estado |
| Metadata | Adjuntar tus propios datos a cualquier objeto |
