> ## 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.
# Referencia de la API
> URL base, auth, forma de respuesta, paginación, errores, parámetros de tiempo y referencias de app de la API REST de Data Hub, más un índice por recurso.
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`:
```http theme={null}
Authorization: Bearer
```
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.
```json theme={null}
{ "data": { "...": "..." } }
```
```json theme={null}
{
"error": {
"code": "unauthorized",
"category": "forbidden",
"message": "valid API key or access token required (Authorization: Bearer )",
"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`:
```json theme={null}
{
"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` | `/`. 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
Búsqueda, detalle, versiones, README, specs y traducciones.
Iniciar, sondear, listar, cancelar, leer registros y trazas de depuración.
Contenedores persistentes de resultados de ejecución y flags de retención.
Gasto acumulado y agregados de facturación por periodo y dimensión.
Credenciales upstream que los autores guardan para sus propias apps.
Borrador → Build → Release, interruptores ops, compartición, traducciones, herramientas de contrato y analítica de publicador.