> ## Documentation Index
> Fetch the complete documentation index at: https://docs.olostep.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Objectgeoriënteerde API

> Begrijpen hoe Olostep API-objecten samenwerken

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    |

<Note>
  **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.
</Note>

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

<Note>
  **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.
</Note>

### 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.

```bash theme={null}
# 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](/api-reference/common/webhooks) om gebeurtenissen te ontvangen wanneer objecten van status veranderen.

```json theme={null}
{
  "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](/api-reference/common/metadata). Hiermee kun je Olostep resources koppelen aan je interne systemen.

```json theme={null}
{
  "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               |