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

# Objektorientierte API

> Verstehen, wie Olostep API-Objekte zusammenarbeiten

Die API von Olostep ist objektorientiert gestaltet. Dieses Design zu verstehen, hilft dir, effektivere Integrationen zu entwickeln.

***

## Alles ist ein Objekt

Jede Ressource in Olostep ist ein Objekt mit einer eindeutigen Kennung. Egal, ob du es über die API, das SDK oder das Dashboard erstellst – du erhältst ein Objekt, auf das du verweisen, das du aktualisieren und abfragen kannst.

| Ressource | Objekt-ID-Format | Beispiel          |
| --------- | ---------------- | ----------------- |
| 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` |

***

## Objekte können Lebenszyklen haben

Einige Olostep-Objekte verfolgen den Status über ein `status`-Feld. Dieses Zustandsmaschinenmuster ermöglicht es dir, genau zu wissen, wo sich jede Ressource in ihrem Lebenszyklus befindet.

### Batches

Batches haben zwei Status-Ebenen: den **Batch** selbst und die einzelnen **Items**.

**Batch-Status:**

```
in_progress → completed
```

| Status        | Beschreibung               |
| ------------- | -------------------------- |
| `in_progress` | URLs werden gescraped      |
| `completed`   | Verarbeitung abgeschlossen |

<Note>
  **Batch-Fehler sind extrem selten.** Batches werden fast immer abgeschlossen – selbst wenn einige URLs fehlschlagen, erreicht der Batch selbst den Status `completed`. Im seltenen Fall eines katastrophalen Infrastrukturfehlers (z.B. LLM-Dienstunterbrechung während der Anreicherung) kann der Batch fehlschlagen. Dies betrifft weniger als 0,01% der Batches.
</Note>

**Item-Status:**

Jede URL in einem Batch wird als einzelnes Item mit eigenem Status verfolgt:

| Status    | Beschreibung                      |
| --------- | --------------------------------- |
| `success` | URL erfolgreich gescraped         |
| `failed`  | URL konnte nicht gescraped werden |

Items können aus folgenden Gründen fehlschlagen:

* URL ist blockiert oder gibt einen Fehler zurück
* Parser-Ausgabe fehlt
* Netzwerk-/Abruffehler

Fehlgeschlagene Items enthalten ein `error`-Objekt mit `code` und `message`, die den Fehler erklären. Der Batch wird trotzdem abgeschlossen – überprüfe den Status jedes Items bei der Verarbeitung der Ergebnisse.

### Crawls

```
in_progress → completed
```

| Status        | Beschreibung                               |
| ------------- | ------------------------------------------ |
| `in_progress` | URLs werden aktiv entdeckt und verarbeitet |
| `completed`   | Crawlen abgeschlossen                      |

<Note>
  **Crawls werden immer abgeschlossen.** Selbst wenn ein Crawl 0 URLs findet (aufgrund von robots.txt-Blockierung oder ungültiger Start-URL), wird der Crawl-Status `completed` sein. Überprüfe das `pages_count`-Feld, um die Ergebnisse zu verifizieren.
</Note>

### Monitore

Monitore sind langlebige Objekte mit einem reicheren Lebenszyklus als einmalige Ressourcen:

```
provisioning → active ⇄ paused
            ↘ failed
```

| Status         | Beschreibung                                                                            |
| -------------- | --------------------------------------------------------------------------------------- |
| `provisioning` | Agent, Spezifikation, Planer und Zeitplan werden eingerichtet                           |
| `active`       | Zeitplan aktiviert; Läufe werden gemäß `schedule.frequency` ausgeführt                  |
| `paused`       | Zeitplan über `POST /v1/monitors/:monitor_id/pause` deaktiviert                         |
| `failed`       | Bereitstellung oder Zeitplanaktualisierung fehlgeschlagen (`error_message` ist gesetzt) |
| `deleted`      | Soft-gelöscht über `DELETE /v1/monitors/:monitor_id`                                    |

Das Erstellen eines Monitors gibt HTTP `202` mit `status: provisioning` zurück. Der Monitor wird `active`, sobald die Planung seine verfolgten Ziele löst – poll `GET /v1/monitors/:monitor_id` oder streame Bereitstellungsereignisse mit `?stream=1`. Nur `active` Monitore können pausiert werden, und nur `paused` Monitore können fortgesetzt werden. Updates geben `409` zurück, während der Monitor noch `provisioning` ist.

***

## Retrieve-Muster

Viele Objekte erzeugen Inhalte, die später abgerufen werden können. Das `retrieve_id`-Muster ermöglicht es dir, Inhalte abzurufen, ohne sie erneut zu verarbeiten.

```bash theme={null}
# Inhalte mit retrieve_id abrufen
curl "https://api.olostep.com/v1/retrieve?retrieve_id=6h89o8u1kt" \
  -H "Authorization: Bearer <your_token>"
```

Dieses Muster wird verwendet von:

* **Batch-Items** — Jede verarbeitete URL erhält eine `retrieve_id`
* **Crawl-Seiten** — Jede gecrawlte Seite erhält eine `retrieve_id`

Der `/v1/retrieve`-Endpunkt akzeptiert den `formats`-Parameter, um anzugeben, welche Inhaltstypen zurückgegeben werden sollen (`html`, `markdown`, `json`, `text`).

***

## Webhooks: Ereignisgesteuerte Aktualisierungen

Anstatt auf Statusänderungen zu warten, konfiguriere [Webhooks](/api-reference/common/webhooks), um Ereignisse zu erhalten, wenn Objekte ihren Zustand ändern.

```json theme={null}
{
  "event": "batch.completed",
  "data": {
    "id": "batch_xyz789",
    "status": "completed",
    "items_total": 100,
    "items_completed": 100
  }
}
```

***

## Metadaten: Deine Daten neben unseren

Füge benutzerdefinierte Schlüssel-Wert-Paare zu Objekten hinzu, indem du [Metadaten](/api-reference/common/metadata) verwendest. Dies ermöglicht es dir, Olostep-Ressourcen mit deinen internen Systemen zu verknüpfen.

```json theme={null}
{
  "items": [{"url": "https://example.com"}],
  "metadata": {
    "order_id": "12345",
    "customer": "acme-corp"
  }
}
```

***

## Zusammenfassung

| Konzept          | Beschreibung                                            |
| ---------------- | ------------------------------------------------------- |
| **Objekte**      | Jede Ressource hat eine eindeutige ID und ist abfragbar |
| **Lebenszyklen** | Fortschritt über das `status`-Feld verfolgen            |
| **Retrieve**     | Inhalte später mit `retrieve_id` abrufen                |
| **Webhooks**     | Benachrichtigungen bei Zustandsänderungen erhalten      |
| **Metadaten**    | Eigene Daten an jedes Objekt anhängen                   |