Référence API

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 :

Authorization: Bearer <your API key>

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.

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

{
  "error": {
    "code": "unauthorized",
    "category": "forbidden",
    "message": "valid API key or access token required (Authorization: Bearer <credential>)",
    "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 :

{
  "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`	`<namespace>/<app_name>`. 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

Discover Data Apps

Recherche, détail, versions, README, specs et traductions.

Runs and results

Démarrer, interroger, lister, annuler, lire les enregistrements et traces de débogage.

Datasets

Conteneurs persistants pour résultats d’exécution et flags de rétention.

Account and billing

Dépenses cumulées et agrégats de facturation par période et dimension.

Secrets

Credentials upstream que les auteurs stockent pour leurs propres apps.

Publishing and operations

Brouillon → Build → Release, interrupteurs ops, partage, traductions, outils de contrat et analytique éditeur.

BIEN DÉMARRER

DÉMARRAGE RAPIDE

RÉFÉRENCE

DATA HUB API

URL de base

Authentification

Forme de la réponse

Erreurs

Paramètres temporels

Références d’app

États d’exécution

Groupes d’endpoints

Discover Data Apps

Runs and results

Datasets

Account and billing

Secrets

Publishing and operations

​URL de base

​Authentification

​Forme de la réponse

​Erreurs

​Pagination

​Paramètres temporels

​Références d’app

​États d’exécution

​Groupes d’endpoints

Discover Data Apps

Runs and results

Datasets

Account and billing

Secrets

Publishing and operations

URL de base

Authentification

Forme de la réponse

Erreurs

Pagination

Paramètres temporels

Références d’app

États d’exécution

Groupes d’endpoints