API-Referenz

Dieser Abschnitt listet jeden öffentlichen Data-Hub-REST-Endpoint nach Ressource. Jede Endpoint-Seite behandelt Methode und Pfad, Auth, Parameter, echte Antwortbeispiele und Feldnotizen, mögliche Fehler sowie die passende Client-Bibliotheksmethode. Diese Seite enthält nur Konventionen, die alle Endpoints teilen.

Basis-URL

Element	Wert
Basis-URL	`https://api-datahub.octoparse.com`
Pfadpräfix	Jeder Endpoint beginnt mit `/v1`
Protokoll	HTTPS; Request- und Response-Bodies sind JSON

Der /v1-Vertrag ist nur additiv: neue Felder und Endpoints können im Laufe der Zeit erscheinen, veröffentlichte Felder behalten Name und Bedeutung. Unbekannte Felder bei der Integration ignorieren und nicht von der Feldreihenfolge abhängen.

Authentifizierung

Authentifizierte Endpoints nutzen Standard-Bearer-Auth. Den Data-Hub-API-Schlüssel in den Authorization-Header setzen:

Authorization: Bearer <your API key>

API-Schlüssel im Octoparse-Account-Center erstellen. Access-Tokens aus Web-Login oder OAuth gehören an dieselbe Stelle. Jede Endpoint-Seite kennzeichnet ihre Auth-Klasse:

Klasse	Bedeutung
Anonym	Keine Credential erforderlich
Optional authentifiziert	Funktioniert ohne Credential; mit Credential freigeschaltete Filter oder mehr Inhalt
API-Schlüssel erforderlich	Credential erforderlich
Nur App-Autor	Credential erforderlich, und nur der Publisher dieser App darf aufrufen; alle anderen erhalten `404`

Die Data-Hub-API akzeptiert nur Authorization: Bearer. Credentials in URL-Query-Parametern werden nicht akzeptiert. Das ist nicht dieselbe Konvention wie der Octoparse-Scraper-MCP in der Top-Navigation, der einen x-api-key-Header nutzt. Nicht mischen. Behandeln Sie einen API-Schlüssel wie eine Konto-Credential: nie in Repo, Shared Config oder öffentlichen Screenshot committen.

Antwortform

Erfolgreiche Antworten wrappen den Payload in data. Fehlerantworten wrappen den Payload in error. Beides erscheint nie zusammen.

{ "data": { "...": "..." } }

{
  "error": {
    "code": "unauthorized",
    "category": "forbidden",
    "message": "valid API key or access token required (Authorization: Bearer <credential>)",
    "retryable": false
  }
}

Einige Endpoints liefern Non-JSON-Inhalt (rohes Markdown, CSV-/JSONL-Text oder Zip-Binary). Diese Seiten weisen ausdrücklich darauf hin.

Fehler

Feld	Bedeutung
`code`	Stabile Fehler-ID für Branching, z. B. `unauthorized`, `app-not-found`, `balance-negative`
`category`	Breite Klasse: `invalid_input`, `not_found`, `forbidden` oder `temporary`
`message`	Englischer entwicklerseitiger Text. Lesen; nicht darauf branchen
`retryable`	Ob ein Retry derselben Anfrage erfolgreich sein kann. Bei `true` backoffen und erneut versuchen. Bei `false` Request fixen oder auf User-Aktion warten
`details`	Nur bei Input-Validierungsfehlern: Array aus feldbezogenen `path`- und `message`-Items

Jede Endpoint-Seite listet endpoint-spezifische Codes. Diese erscheinen auf den meisten Endpoints:

HTTP	`code`	Bedeutung
401	`unauthorized`	Fehlender oder ungültiger API-Schlüssel
404	`*-not-found`	Objekt existiert nicht oder ist für die aktuelle Credential unsichtbar. Beide Fälle werden absichtlich nicht unterschieden
400	`invalid-input`	Request-Body oder Parameter sind ungültig

Denselben 404 für „fehlend“ und „unsichtbar“ zurückzugeben ist Absicht: private Apps, Runs anderer und Datasets anderer leaken ihre Existenz nie über den Fehlercode.

Paginierung

Listen-Endpoints nutzen offset/limit-Query-Parameter und geben ein pagination-Objekt zurück:

{
  "data": {
    "items": [ "..." ],
    "pagination": {
      "offset": 0,
      "limit": 50,
      "count": 50,
      "total": 132,
      "has_more": true
    }
  }
}

total ist die gefilterte Gesamtzahl. Bei has_more = true count zu offset addieren und fortfahren. Per-Endpoint-limit-Caps stehen auf der jeweiligen Seite.

Zeitparameter

Endpoints mit Zeitraum (Run-Liste, Abrechnungsaggregation, Publisher-Analytics) akzeptieren ISO-8601-Timestamps. Expliziten Offset bevorzugen, z. B. 2026-09-01T00:00:00+08:00. Unix-Epoch-Sekunden werden nicht akzeptiert.

App-Referenzen

Überall wo eine App identifiziert wird, funktionieren beide Formen:

Form	Beispiel	Hinweise
Stabile ID	`app_a1b2c3d4e5f6`	Überlebt Renames. Für langlebige Integrationen bevorzugen
Menschenlesbar	`carol/reviews-query`	`<namespace>/<app_name>`. Bricht, wenn Publisher- oder App-Name sich ändert

Point-to-point freigegebene Apps erscheinen nicht in der Market-Suche. Mit dem Shared-with-me-Filter auf dem Search-Endpoint listen. Für Scheduled Jobs und langlebige Automation app_id speichern.

Run-Status

Status	Bedeutung	Endzustand
`PENDING`	Akzeptiert, noch nicht in Queue	Nein
`QUEUED`	Wartet auf Ausführung	Nein
`RUNNING`	Laufend	Nein
`SUCCEEDED`	Erfolgreich	Ja
`PARTIALLY_SUCCEEDED`	Teilweise erfolgreich; erzeugte Datensätze nutzbar	Ja
`FAILED`	Fehlgeschlagen; keine Datengebühr	Ja
`CANCELLED`	Abgebrochen; erzeugte Datensätze bleiben und werden abgerechnet	Ja
`EXPIRED`	Zeitüberschreitung	Ja

Endpoint-Gruppen

Data Apps entdecken

Suche, Detail, Versionen, README, Specs und Übersetzungen.

Runs und Ergebnisse

Starten, pollen, listen, abbrechen, Datensätze lesen und Debug-Traces.

Datasets

Persistente Container für Run-Ergebnisse und Retention-Flags.

Konto und Abrechnung

Lifetime-Spend und Abrechnungsaggregate nach Periode und Dimension.

Secrets

Upstream-Credentials, die App-Autoren für eigene Apps speichern.

Publishing und Operations

Draft → Build → Release, Ops-Schalter, Sharing, Übersetzungen, Contract-Tools und Publisher-Analytics.

ERSTE SCHRITTE

SCHNELLSTART

REFERENZ

DATA HUB API

Basis-URL

Authentifizierung

Antwortform

Fehler

Paginierung

Zeitparameter

App-Referenzen

Run-Status

Endpoint-Gruppen

Data Apps entdecken

Runs und Ergebnisse

Datasets

Konto und Abrechnung

Secrets

Publishing und Operations

​Basis-URL

​Authentifizierung

​Antwortform

​Fehler

​Paginierung

​Zeitparameter

​App-Referenzen

​Run-Status

​Endpoint-Gruppen

Data Apps entdecken

Runs und Ergebnisse

Datasets

Konto und Abrechnung

Secrets

Publishing und Operations

Basis-URL

Authentifizierung

Antwortform

Fehler

Paginierung

Zeitparameter

App-Referenzen

Run-Status

Endpoint-Gruppen