Documentation de l'API

Un endpoint et un champ op. Tous les endpoints partagent la même forme de requête.

Démarrage rapide

Envie de voir d'abord ce qui revient ? Essayez le Playground. Inutile de lire cette page avant.

Inscrivez-vous pour obtenir une clé (l'offre gratuite inclut 100 crédits), puis :

curl -X POST https://widefetch.com/v1/call \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"op":"google.search","params":{"keyword":"vector database"}}'

Authentification

Authorization: Bearer sk_…. Les clés sont émises dans la console et affichées en entier une seule fois ; nous stockons un hash.

La révocation est immédiate. Si une clé fuite, révoquez-la et émettez-en une nouvelle.

Faire un appel

POST /v1/call

Champ	Type	Description
op	string	L'endpoint à appeler, voir le tableau ci-dessous
params	object	Les paramètres de cet endpoint

Synchrone borné : les appels qui se terminent en environ 25 secondes renvoient directement le résultat. Les plus longs renvoient status: "running" et un request_id à interroger. Les endpoints basés sur un navigateur (executor: browser) prennent plus souvent du temps ; les http et api répondent généralement en une ou deux secondes.

{
  "request_id": "req_7Qn1vK…",
  "status": "done",          // done | running | failed
  "outcome": "ok",
  "credits_charged": 1,      // 0 when the call failed
  "timing": {
    "queued_ms": 400,
    "ran_ms": 8100,
    "attempts": 1            // >1 means it was retried
  },
  "result": { "items": [ … ] }
}

Polling

GET /v1/requests/{request_id}

Même forme de réponse que ci-dessus. Interrogez toutes les 2 secondes, en espaçant jusqu'à 5.

Règles de facturation

Les appels échoués sont gratuits. Captchas, limites de débit, timeouts et réponses non reconnues sont pour nous et remboursés automatiquement.
Les résultats vides sont facturés. « Rien trouvé » est une réponse, pas un échec, et le coût est déjà engagé.

Outcomes facturés

no_resultsokverified_page

Outcomes gratuits

bad_paramscancelledcaptchaclaim_timeoutneeds_mappingnot_configuredrate_limitedtimeouttransient

Tout outcome non listé est gratuit. Facturer par défaut transformerait nos bugs en facture pour vous.

Endpoints

op	credit	Paramètres	Description
brave.search	1	keyword*, limit, region, language	Résultats de recherche web : titre, URL et extrait. Rapide, conçu pour de nombreux appels en parallèle.	Essayer
github.repo	1	repo*	Un dépôt GitHub : étoiles, forks, issues ouvertes, langage, licence et topics.	Essayer
github.search	1	query*, sort, order, limit	Recherche de dépôts GitHub, triée par étoiles, forks ou dernière mise à jour.	Essayer
google.search	1	keyword*, limit, language, region	Résultats naturels Google : titre, URL, domaine source et extrait.	Essayer
google.trends	1	keyword*, region	Intérêt de recherche Google Trends : série hebdomadaire sur les deux dernières années (0–100).	Essayer
hn.comments	1	keyword*, limit, sort, since	Recherche dans les commentaires Hacker News : texte original, auteur et article d'origine.	Essayer
hn.item	1	id*, comments	Un fil Hacker News complet : le texte du post et tous ses commentaires.	Essayer
hn.search	1	keyword*, limit, sort, since, min_points	Articles Hacker News : titre, lien, auteur, points, nombre de commentaires et date.	Essayer

Codes d'erreur

Code	Signification	Que faire
400	Paramètres invalides ou op inconnu	Corrigez la requête. Non facturé.
401	Clé incorrecte ou révoquée	Utilisez une autre clé
402	Plus de crédits	Changez d'offre ou attendez la remise à zéro mensuelle
403	La liste d'autorisation de cette clé n'inclut pas cet op	Consultez le champ `error` de la réponse
429	Limite de débit ou de parallélisme dépassée	Patientez puis réessayez. Non facturé.
502	Problème de notre côté ou en amont	Réessayez. Non facturé.

Limites de débit

Chaque clé autorise par défaut 60 appels par minute avec un parallélisme limité. Au-delà, vous recevez 429, pas une file d'attente.

Besoin de plus ? Contactez-nous.