> ## 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.
# Référence API
> URL de base, auth, forme de réponse, pagination, erreurs, paramètres temporels et références d’app de l’API REST Data Hub, plus un index par ressource.
Cette section liste chaque endpoint REST public Data Hub par ressource. Chaque page couvre méthode et chemin, auth, paramètres, exemples réels, erreurs possibles et la méthode cliente équivalente. Cette page ne contient que les conventions partagées.
## URL de base
| Élément | Valeur |
| ----------------- | ---------------------------------------------- |
| URL de base | `https://api-datahub.octoparse.com` |
| Préfixe de chemin | Tous les endpoints commencent par `/v1` |
| Protocole | HTTPS ; corps de requête et de réponse en JSON |
Le contrat `/v1` est additif uniquement : de nouveaux champs et endpoints peuvent apparaître, mais les champs publiés gardent nom et sens. Ignorez les champs inconnus.
## Authentification
Les endpoints authentifiés utilisent Bearer standard. Placez la clé API Data Hub dans l’en-tête `Authorization` :
```http theme={null}
Authorization: Bearer
```
Créez la clé dans le centre de compte Octoparse. Les tokens de login web ou OAuth vont au même endroit.
Chaque page d’endpoint indique sa classe d’auth :
| Classe | Signification |
| -------------------------- | ----------------------------------------------------------------------- |
| Anonyme | Aucune credential requise |
| Auth facultative | Fonctionne sans credential ; avec, filtres connectés ou plus de contenu |
| Clé API requise | Credential obligatoire |
| Auteur de l’app uniquement | Credential obligatoire et seul l’éditeur peut l’appeler ; sinon `404` |
L’API Data Hub n’accepte que `Authorization: Bearer`. Ne mettez pas de credentials en query. Ce n’est pas la convention `x-api-key` du MCP scraping Octoparse. Ne les mélangez pas. Traitez la clé API comme credential de compte.
## Forme de la réponse
Le succès encapsule la charge dans `data`. L’erreur dans `error`. Jamais ensemble.
```json theme={null}
{ "data": { "...": "..." } }
```
```json theme={null}
{
"error": {
"code": "unauthorized",
"category": "forbidden",
"message": "valid API key or access token required (Authorization: Bearer )",
"retryable": false
}
}
```
Quelques endpoints renvoient du non-JSON (Markdown brut, texte CSV/JSONL ou zip binaire). Ces pages le signalent explicitement.
## Erreurs
| Champ | Signification |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code` | Id d’erreur stable pour brancher, par ex. `unauthorized`, `app-not-found`, `balance-negative` |
| `category` | Classe large : `invalid_input`, `not_found`, `forbidden` ou `temporary` |
| `message` | Texte anglais pour développeurs. Lisez-le ; ne branchez pas dessus |
| `retryable` | Si un nouvel essai de la même requête peut réussir. Si `true`, attendez et réessayez. Si `false`, corrigez la requête ou attendez une action utilisateur |
| `details` | Seulement en échecs de validation d’entrée : tableau d’éléments `path` et `message` au niveau champ |
Chaque page d’endpoint liste des codes propres. Ceux-ci apparaissent sur la plupart des endpoints :
| HTTP | `code` | Signification |
| ---- | --------------- | --------------------------------------------------------------------------------------------------------------------- |
| 401 | `unauthorized` | Clé API manquante ou invalide |
| 404 | `*-not-found` | L’objet n’existe pas ou est invisible pour la credential actuelle. Les deux cas ne sont volontairement pas distingués |
| 400 | `invalid-input` | Le corps ou les paramètres de la requête sont invalides |
Renvoyer le même `404` pour « manquant » et « invisible » est intentionnel : apps privées, exécutions d’autrui et datasets d’autrui ne fuient jamais l’existence via le code d’erreur.
## Pagination
Les endpoints de liste utilisent `offset` / `limit` et renvoient un objet `pagination` :
```json theme={null}
{
"data": {
"items": [ "..." ],
"pagination": {
"offset": 0,
"limit": 50,
"count": 50,
"total": 132,
"has_more": true
}
}
}
```
`total` est le total filtré. Quand `has_more` est `true`, ajoutez `count` à `offset` et continuez. Les plafonds `limit` par endpoint sont documentés sur chaque page.
## Paramètres temporels
Les endpoints à plage temporelle (liste d’exécutions, agrégation de facturation, analytique éditeur) acceptent des horodatages ISO-8601 absolus avec offset explicite.
## Références d’app
Partout où une app est identifiée, les deux formes marchent :
| Forme | Exemple | Notes |
| --------- | --------------------- | ------------------------------------------------------------------- |
| Id stable | `app_a1b2c3d4e5f6` | Survivit aux renommages. Préférez-le pour les intégrations durables |
| Lisible | `carol/reviews-query` | `/`. Se casse si l’éditeur ou le nom change |
Les apps partagées point à point n’apparaissent pas dans la recherche market. Listez-les avec la vue shared-with-me.
## États d’exécution
| État | Signification | Terminal |
| --------------------- | -------------------------------------------------------- | -------- |
| `PENDING` | Acceptée, pas encore en file | Non |
| `QUEUED` | En attente d’exécution | Non |
| `RUNNING` | En cours | Non |
| `SUCCEEDED` | Réussi | Oui |
| `PARTIALLY_SUCCEEDED` | Succès partiel ; enregistrements produits utilisables | Oui |
| `FAILED` | Échec ; pas de frais de données | Oui |
| `CANCELLED` | Annulée ; enregistrements produits conservés et facturés | Oui |
| `EXPIRED` | Délai dépassé | Oui |
## Groupes d’endpoints
Recherche, détail, versions, README, specs et traductions.
Démarrer, interroger, lister, annuler, lire les enregistrements et traces de débogage.
Conteneurs persistants pour résultats d’exécution et flags de rétention.
Dépenses cumulées et agrégats de facturation par période et dimension.
Credentials upstream que les auteurs stockent pour leurs propres apps.
Brouillon → Build → Release, interrupteurs ops, partage, traductions, outils de contrat et analytique éditeur.