Referencia de la API

Esta sección lista cada endpoint REST público de Data Hub por recurso. Cada página cubre método y ruta, autenticación, parámetros, ejemplos reales y notas de campos, errores posibles y el método equivalente de la librería cliente. Esta página solo recoge las convenciones compartidas.

URL base

Elemento	Valor
URL base	`https://api-datahub.octoparse.com`
Prefijo de ruta	Todos los endpoints empiezan por `/v1`
Protocolo	HTTPS; cuerpos de solicitud y respuesta en JSON

El contrato /v1 solo crece: pueden aparecer campos y endpoints nuevos, pero los publicados no cambian de nombre ni de significado. Ignore campos desconocidos y no dependa del orden.

Autenticación

Los endpoints autenticados usan Bearer estándar. Ponga la API key de Data Hub en la cabecera Authorization:

Authorization: Bearer <your API key>

Cree la clave en el centro de cuentas de Octoparse. Los tokens de login web u OAuth van en el mismo sitio. Cada página de endpoint indica su clase de auth:

Clase	Significado
Anónimo	Sin credencial
Autenticación opcional	Funciona sin credencial; con ella desbloquea filtros de sesión o más contenido
API key obligatoria	Credencial obligatoria
Solo autor de la app	Credencial obligatoria y solo el publicador puede llamarlo; el resto recibe `404`

La API de Data Hub solo acepta Authorization: Bearer. No ponga credenciales en la query. No es la misma convención que el MCP de scraping de Octoparse (x-api-key). No las mezcle. Trate la API key como credencial de cuenta.

Forma de la respuesta

El éxito envuelve la carga en data. El error la envuelve en error. Nunca aparecen juntos.

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

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

Algunos endpoints devuelven contenido no JSON (Markdown crudo, texto CSV/JSONL o zip binario). Esas páginas lo indican explícitamente.

Errores

Campo	Significado
`code`	Id de error estable para ramificar, por ejemplo `unauthorized`, `app-not-found`, `balance-negative`
`category`	Clase amplia: `invalid_input`, `not_found`, `forbidden` o `temporary`
`message`	Texto en inglés para desarrolladores. Léalo; no ramifique con él
`retryable`	Si un reintento de la misma solicitud puede funcionar. Si `true`, espere y reintente. Si `false`, corrija la solicitud o espere acción del usuario
`details`	Solo en fallos de validación de entrada: array de ítems `path` y `message` a nivel de campo

Cada página de endpoint lista códigos propios. Estos aparecen en la mayoría de endpoints:

HTTP	`code`	Significado
401	`unauthorized`	API key ausente o no válida
404	`*-not-found`	El objeto no existe o es invisible para la credencial actual. Los dos casos no se distinguen a propósito
400	`invalid-input`	El cuerpo o los parámetros de la solicitud no son válidos

Devolver el mismo 404 para «no existe» e «invisible» es a propósito: apps privadas, ejecuciones ajenas y datasets ajenos nunca filtran existencia por el código de error.

Paginación

Los endpoints de listado usan offset / limit y devuelven un objeto pagination:

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

total es el total filtrado. Cuando has_more es true, sume count a offset y continúe. Los topes de limit por endpoint se documentan en cada página.

Parámetros de tiempo

Los endpoints con rango temporal (listado de ejecuciones, agregación de facturación, analítica de publicador) aceptan marcas ISO-8601 absolutas con offset explícito.

Referencias de app

Donde se identifica una app, ambas formas valen:

Forma	Ejemplo	Notas
Id estable	`app_a1b2c3d4e5f6`	Sobrevive a renombres. Prefiéralo en integraciones duraderas
Legible	`carol/reviews-query`	`<namespace>/<app_name>`. Se rompe si cambia el publicador o el nombre

Las apps compartidas punto a punto no aparecen en la búsqueda del market. Listelas con la vista shared-with-me.

Estados de ejecución

Estado	Significado	Terminal
`PENDING`	Aceptada, aún no en cola	No
`QUEUED`	En espera de ejecución	No
`RUNNING`	En curso	No
`SUCCEEDED`	Correcto	Sí
`PARTIALLY_SUCCEEDED`	Éxito parcial; los registros producidos son usables	Sí
`FAILED`	Falló; sin tarifa de datos	Sí
`CANCELLED`	Cancelada; se conservan y facturan los registros producidos	Sí
`EXPIRED`	Tiempo agotado	Sí

Grupos de endpoints

Discover Data Apps

Búsqueda, detalle, versiones, README, specs y traducciones.

Runs and results

Iniciar, sondear, listar, cancelar, leer registros y trazas de depuración.

Datasets

Contenedores persistentes de resultados de ejecución y flags de retención.

Account and billing

Gasto acumulado y agregados de facturación por periodo y dimensión.

Secrets

Credenciales upstream que los autores guardan para sus propias apps.

Publishing and operations

Borrador → Build → Release, interruptores ops, compartición, traducciones, herramientas de contrato y analítica de publicador.

PRIMEROS PASOS

INICIO RÁPIDO

REFERENCIA

DATA HUB API

URL base

Autenticación

Forma de la respuesta

Errores

Paginación

Parámetros de tiempo

Referencias de app

Estados de ejecución

Grupos de endpoints

Discover Data Apps

Runs and results

Datasets

Account and billing

Secrets

Publishing and operations

​URL base

​Autenticación

​Forma de la respuesta

​Errores

​Paginación

​Parámetros de tiempo

​Referencias de app

​Estados de ejecución

​Grupos de endpoints

Discover Data Apps

Runs and results

Datasets

Account and billing

Secrets

Publishing and operations

URL base

Autenticación

Forma de la respuesta

Errores

Paginación

Parámetros de tiempo

Referencias de app

Estados de ejecución

Grupos de endpoints