Objektorientierte API

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

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.

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

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.

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.

# 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, um Ereignisse zu erhalten, wenn Objekte ihren Zustand ändern.

{
  "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 verwendest. Dies ermöglicht es dir, Olostep-Ressourcen mit deinen internen Systemen zu verknüpfen.

{
  "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

Allgemein

Abschürfungen

Chargen

Durchläufe

Karten

Antworten

Suche

Monitore

Dateien

Zeitpläne

Abrufen

Kontostand & Abrechnung

Alles ist ein Objekt

Objekte können Lebenszyklen haben

Batches

Crawls

Monitore

Retrieve-Muster

Webhooks: Ereignisgesteuerte Aktualisierungen

Metadaten: Deine Daten neben unseren

Zusammenfassung

​Alles ist ein Objekt

​Objekte können Lebenszyklen haben

​Batches

​Crawls

​Monitore

​Retrieve-Muster

​Webhooks: Ereignisgesteuerte Aktualisierungen

​Metadaten: Deine Daten neben unseren

​Zusammenfassung

Alles ist ein Objekt

Objekte können Lebenszyklen haben

Batches

Crawls

Monitore

Retrieve-Muster

Webhooks: Ereignisgesteuerte Aktualisierungen

Metadaten: Deine Daten neben unseren

Zusammenfassung