> ## Documentation Index
> Fetch the complete documentation index at: https://www.octoparse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Riferimento API
> URL di base, autenticazione, forma della risposta, paginazione, errori, parametri temporali e riferimenti app dell’API REST Data Hub, più indice per risorsa.
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`:
```http theme={null}
Authorization: Bearer
```
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.
```json theme={null}
{ "data": { "...": "..." } }
```
```json theme={null}
{
"error": {
"code": "unauthorized",
"category": "forbidden",
"message": "valid API key or access token required (Authorization: Bearer )",
"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`:
```json theme={null}
{
"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` | `/`. 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
Ricerca, dettaglio, versioni, README, spec e traduzioni.
Avvia, poll, elenca, annulla, leggi record e trace di debug.
Container persistenti per risultati run e flag di retention.
Spesa lifetime e aggregati di fatturazione per periodo e dimensione.
Credenziali upstream che gli autori salvano per le proprie app.
Draft → Build → Release, switch ops, sharing, traduzioni, tool contratto e analytics publisher.