De API van Olostep is ontworpen rond objecten. Het begrijpen van dit ontwerp helpt je om effectievere integraties te bouwen.
Alles is een Object
Elke resource in Olostep is een object met een unieke identificatie. Of je het nu creëert via de API, SDK of dashboard — je krijgt een object terug dat je kunt refereren, bijwerken en opvragen.
| Resource | Object ID Formaat | Voorbeeld |
|---|
| 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 |
Objecten Kunnen Levenscycli Hebben
Sommige Olostep-objecten volgen de status via een status veld. Dit toestandsmachinepatroon laat je precies weten waar elke resource zich in zijn levenscyclus bevindt.
Batches
Batches hebben twee niveaus van status: de batch zelf en individuele items.
Batch Status:
| Status | Beschrijving |
|---|
in_progress | URL’s worden gescraped |
completed | Verwerking voltooid |
Batch-niveau fouten zijn uiterst zeldzaam. Batches worden bijna altijd voltooid — zelfs als sommige URL’s falen, bereikt de batch zelf de completed status. In het zeldzame geval van een catastrofale infrastructuurfout (bijv. LLM-service uitval tijdens verrijking), kan de batch falen. Dit treft minder dan 0,01% van de batches.
| Status | Beschrijving |
|---|
success | URL succesvol gescraped |
failed | URL kon niet worden gescraped |
- URL is geblokkeerd of retourneert een fout
- Parser output ontbreekt
- Netwerk/fetch fouten
Mislukte items bevatten een error object met code en message die de fout uitleggen. De batch wordt nog steeds voltooid — controleer de status van elk item bij het verwerken van resultaten.
Crawls
| Status | Beschrijving |
|---|
in_progress | Actief URL’s ontdekken en verwerken |
completed | Crawlen voltooid |
Crawls worden altijd voltooid. Zelfs als een crawl 0 URL’s vindt (door robots.txt blokkering of ongeldige start-URL), zal de crawl status completed zijn. Controleer het pages_count veld om resultaten te verifiëren.
Monitors
Monitors zijn langlevende objecten met een rijkere levenscyclus dan eenmalige resources:
provisioning → active ⇄ paused
↘ failed
| Status | Beschrijving |
|---|
provisioning | Agent, spec, planner en schema worden opgezet |
active | Schema ingeschakeld; runs worden uitgevoerd op schedule.frequency |
paused | Schema uitgeschakeld via POST /v1/monitors/:monitor_id/pause |
failed | Provisioning of schema-update mislukt (error_message is ingesteld) |
deleted | Zacht verwijderd via DELETE /v1/monitors/:monitor_id |
202 met status: provisioning. De monitor wordt active zodra de planning zijn getraceerde doelen oplost — poll GET /v1/monitors/:monitor_id of stream provisioning events met ?stream=1. Alleen active monitors kunnen gepauzeerd worden, en alleen paused monitors kunnen hervat worden. Updates retourneren 409 terwijl de monitor nog provisioning is.
Retrieve Patroon
Veel objecten produceren inhoud die later kan worden opgehaald. Het retrieve_id patroon laat je inhoud ophalen zonder opnieuw te verwerken.
# Haal inhoud op met retrieve_id
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
-H "Authorization: Bearer <your_token>"
- Batch items — Elke verwerkte URL krijgt een
retrieve_id
- Crawl pagina’s — Elke gecrawlde pagina krijgt een
retrieve_id
De /v1/retrieve endpoint accepteert de formats parameter om te specificeren welke inhoudstypen moeten worden geretourneerd (html, markdown, json, text).
Webhooks: Gebeurtenisgestuurde Updates
In plaats van te polleren voor statuswijzigingen, configureer webhooks om gebeurtenissen te ontvangen wanneer objecten van status veranderen.
{
"event": "batch.completed",
"data": {
"id": "batch_xyz789",
"status": "completed",
"items_total": 100,
"items_completed": 100
}
}
Voeg aangepaste sleutel-waarde paren toe aan objecten met behulp van metadata. Hiermee kun je Olostep resources koppelen aan je interne systemen.
{
"items": [{"url": "https://example.com"}],
"metadata": {
"order_id": "12345",
"customer": "acme-corp"
}
}
Samenvatting
| Concept | Beschrijving |
|---|
| Objecten | Elke resource heeft een unieke ID en is opvraagbaar |
| Levenscycli | Volg de voortgang via het status veld |
| Retrieve | Haal later inhoud op met retrieve_id |
| Webhooks | Wordt op de hoogte gebracht wanneer de status verandert |
| Metadata | Voeg je eigen gegevens toe aan elk object |
