Riferimento API

Questa sezione elenca ogni endpoint REST pubblico di Data Hub per risorsa. Ogni pagina endpoint copre metodo e path, auth, parametri, esempi reali di risposta e note sui campi, errori possibili e il metodo della libreria client corrispondente. Questa pagina contiene solo le convenzioni condivise da ogni endpoint.

URL di base

Elemento	Valore
URL di base	`https://api-datahub.octoparse.com`
Prefisso path	Ogni endpoint inizia con `/v1`
Protocollo	HTTPS; body di request e response in JSON

Il contratto /v1 è solo additivo: nel tempo possono comparire nuovi campi ed endpoint, ma i campi pubblicati mantengono nome e significato. Ignora i campi sconosciuti in integrazione e non dipendere dall’ordine dei campi.

Autenticazione

Gli endpoint autenticati usano Bearer auth standard. Metti la API key Data Hub nell’header Authorization:

Authorization: Bearer <your API key>

Crea una API key nel centro account Octoparse. I token di accesso da web login o OAuth vanno nello stesso posto. Ogni pagina endpoint etichetta la sua auth class:

Classe	Significato
Anonimo	Nessuna credenziale richiesta
Autenticazione facoltativa	Funziona senza credenziale; con una sblocchi filtri da loggato o più contenuti
API key obbligatoria	Credenziale obbligatoria
Solo autore app	Credenziale obbligatoria, e solo il publisher di quell’app può chiamarlo; tutti gli altri ricevono `404`

L’API Data Hub accetta solo Authorization: Bearer. Non accetta credenziali nei parametri query dell’URL. Non è la stessa convenzione dell’MCP scraper Octoparse nella navigazione in alto, che usa un header x-api-key. Non mescolarle. Tratta una API key come una credenziale account: non committarla mai in repo, config condivise o screenshot pubblici.

Forma della risposta

Le risposte di successo wrappano il payload in data. Le risposte di errore wrappano il payload in error. Le due non compaiono mai insieme.

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

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

Alcuni endpoint restituiscono contenuto non JSON (Markdown grezzo, testo CSV/JSONL o binary zip). Quelle pagine lo dichiarano esplicitamente.

Errori

Campo	Significato
`code`	ID errore stabile per branching, ad esempio `unauthorized`, `app-not-found`, `balance-negative`
`category`	Classe ampia: `invalid_input`, `not_found`, `forbidden` o `temporary`
`message`	Testo in inglese rivolto agli sviluppatori. Leggilo; non fare branching su di esso
`retryable`	Se un retry della stessa request può riuscire. Se `true`, fai backoff e ritenta. Se `false`, correggi la request o attendi un’azione utente
`details`	Presente solo sui fallimenti di validazione input: array di item `path` e `message` a livello campo

Ogni pagina endpoint elenca i codici unici di quell’endpoint. Questi compaiono sulla maggior parte degli endpoint:

HTTP	`code`	Significato
401	`unauthorized`	API key mancante o non valida
404	`*-not-found`	L’oggetto non esiste o è invisibile alla credenziale corrente. I due casi non sono distinti di proposito
400	`invalid-input`	Body o parametri non validi

Restituire lo stesso 404 per “mancante” e “invisibile” è intenzionale: app private, run di altri e dataset di altri non leakano mai l’esistenza tramite il codice errore.

Paginazione

Gli endpoint di lista usano parametri query offset / limit e restituiscono un oggetto pagination:

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

total è il totale filtrato. Quando has_more è true, aggiungi count a offset e continua. I cap di limit per endpoint sono documentati su ciascuna pagina.

Parametri temporali

Gli endpoint con intervallo temporale (lista run, aggregazione fatturazione, analytics publisher) accettano timestamp ISO 8601. Preferisci un offset esplicito come 2026-09-01T00:00:00+08:00. I secondi Unix epoch non sono accettati.

Riferimenti app

Ovunque un’app sia identificata, funzionano entrambe le forme:

Forma	Esempio	Note
ID stabile	`app_a1b2c3d4e5f6`	Sopravvive ai rename. Preferiscilo per integrazioni longeve
Leggibile	`carol/reviews-query`	`<namespace>/<app_name>`. Si rompe se cambiano publisher o nome app

Le app shared point-to-point non compaiono nella ricerca market. Elencale col filtro shared-with-me sull’endpoint di search. Per job schedulati e automazione longeva salva app_id.

Stati di esecuzione

Stato	Significato	Terminale
`PENDING`	Accettato, non ancora in coda	No
`QUEUED`	In attesa di esecuzione	No
`RUNNING`	In corso	No
`SUCCEEDED`	Riuscito	Sì
`PARTIALLY_SUCCEEDED`	Parzialmente riuscito; i record prodotti sono usabili	Sì
`FAILED`	Fallito; nessuna data fee	Sì
`CANCELLED`	Annullato; i record prodotti restano e sono fatturati	Sì
`EXPIRED`	Timeout	Sì

Gruppi di endpoint

Scopri Data App

Ricerca, dettaglio, versioni, README, spec e traduzioni.

Esecuzioni e risultati

Avvia, poll, elenca, annulla, leggi record e trace di debug.

Dataset

Container persistenti per risultati run e flag di retention.

Account e fatturazione

Spesa lifetime e aggregati di fatturazione per periodo e dimensione.

Secret

Credenziali upstream che gli autori salvano per le proprie app.

Publishing e operations

Draft → Build → Release, switch ops, sharing, traduzioni, tool contratto e analytics publisher.

PER INIZIARE

GUIDA RAPIDA

RIFERIMENTO

DATA HUB API

URL di base

Autenticazione

Forma della risposta

Errori

Paginazione

Parametri temporali

Riferimenti app

Stati di esecuzione

Gruppi di endpoint

Scopri Data App

Esecuzioni e risultati

Dataset

Account e fatturazione

Secret

Publishing e operations

​URL di base

​Autenticazione

​Forma della risposta

​Errori

​Paginazione

​Parametri temporali

​Riferimenti app

​Stati di esecuzione

​Gruppi di endpoint

Scopri Data App

Esecuzioni e risultati

Dataset

Account e fatturazione

Secret

Publishing e operations

URL di base

Autenticazione

Forma della risposta

Errori

Paginazione

Parametri temporali

Riferimenti app

Stati di esecuzione

Gruppi di endpoint