Objectgeoriënteerde API

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:

in_progress → completed

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.

Item Status: Elke URL in een batch wordt gevolgd als een individueel item met zijn eigen status:

Status	Beschrijving
`success`	URL succesvol gescraped
`failed`	URL kon niet worden gescraped

Items kunnen falen door:

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

in_progress → completed

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`

Het creëren van een monitor retourneert HTTP 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>"

Dit patroon wordt gebruikt door:

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
  }
}

Metadata: Jouw Gegevens Naast de Onze

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

Algemeen

Schraapsels

Partijen

Crawls

Kaarten

Antwoorden

Zoeken

Monitoren

Bestanden

Roosters

Ophalen

Saldo & Facturering

Objectgeoriënteerde API

Alles is een Object

Objecten Kunnen Levenscycli Hebben

Batches

Crawls

Monitors

Retrieve Patroon

Webhooks: Gebeurtenisgestuurde Updates

Metadata: Jouw Gegevens Naast de Onze

Samenvatting

​Alles is een Object

​Objecten Kunnen Levenscycli Hebben

​Batches

​Crawls

​Monitors

​Retrieve Patroon

​Webhooks: Gebeurtenisgestuurde Updates

​Metadata: Jouw Gegevens Naast de Onze

​Samenvatting

Alles is een Object

Objecten Kunnen Levenscycli Hebben

Batches

Crawls

Monitors

Retrieve Patroon

Webhooks: Gebeurtenisgestuurde Updates

Metadata: Jouw Gegevens Naast de Onze

Samenvatting