API Should I Bid
La même analyse que l'app, pilotée par vos scripts et vos automatisations : idées de mots-clés, devis, lancement et résultats, avec les mêmes règles de crédits et les mêmes garde-fous.
API REST · JSON · OpenAPI 3.1 · incluse dans toutes les offres payantes
Démarrer
Une clé, un en-tête, une requête.
Dans Should I Bid › Intégrations › Créer une clé. Cochez « Autoriser le lancement d'analyses » si votre script doit lancer des analyses. La clé n'est affichée qu'une seule fois ; seule son empreinte est conservée.
Chaque requête porte l'en-tête Authorization: Bearer sib_live_… Une clé placée dans l'adresse est refusée : elle finirait dans les journaux.
GET /api/v1/account renvoie votre solde, votre offre, vos entreprises et les identifiants de leurs produits.
curl -H "Authorization: Bearer $SIB_API_KEY" https://shouldibid.app/api/v1/accountParcours type
Le parcours Vision complet : générer des idées pour un produit, les chiffrer, les lancer, puis lire les résultats.
Jusqu'à 3 sources : des produits de l'entreprise ou des pages web. La réponse contient les idées nouvelles, celles déjà analysées avec leur score, et un suggestion_batch_id valable 24 heures pour un seul lancement.
POST /api/v1/suggestions
{"sources":[{"product_id":"…"}]}Rien n'est lancé : liste nettoyée, crédits à réserver, solde disponible, plafond du jour et éventuels blocages.
POST /api/v1/analyses/estimate
{"suggestion_batch_id":"…"}max_credits est obligatoire : c'est le montant maximal accepté. Pour un lot Vision, seuls les mots-clés recommandés (score de 50 ou plus) sont débités. Réponse 201 avec l'identifiant de l'analyse.
POST /api/v1/analyses
{"suggestion_batch_id":"…","max_credits":20}Une analyse prend de 3 à 10 minutes : interrogez-la toutes les 30 à 60 secondes jusqu'à la fin, puis lisez les verdicts Enchérir, Tester ou Ne pas enchérir, triés par score.
GET /api/v1/analyses/{analysis_id}Référence
Adresse de base : https://shouldibid.app/api/v1. Réponses en JSON, jamais mises en cache, avec un en-tête X-Request-Id à communiquer au support.
| Méthode | Chemin | Rôle |
|---|---|---|
| GET | /api/v1/account | Compte : offre, crédits disponibles, plafond du jour, entreprises et produits. |
| GET | /api/v1/analyses | Historique des analyses, avec filtres (statut, entreprise, nom) et pagination. |
| POST | /api/v1/analyses | Lance une analyse (consomme des crédits) ; max_credits obligatoire. |
| POST | /api/v1/analyses/estimate | Devis sans rien lancer : crédits à réserver, solde, plafond, blocages. |
| GET | /api/v1/analyses/{analysis_id} | Avancement et résultats d'une analyse, mots-clés triés par score. |
| POST | /api/v1/analyses/{analysis_id}/cancel | Arrête une analyse en cours ; les mots-clés non analysés ne sont pas débités. |
| GET | /api/v1/analyses/{analysis_id}/keywords/{keyword_id} | Détail d'un mot-clé : score, décision, sous-scores, justification, annonceurs. |
| POST | /api/v1/suggestions | Idées de mots-clés Vision depuis 1 à 3 sources (gratuit). |
| GET | /api/v1/openapi.json | Cette référence au format OpenAPI 3.1 (publique, sans clé). |
Garde-fous
Pensées pour qu'un script ne puisse jamais dépenser plus que prévu.
Lecture seule par défaut ; le lancement d'analyses est une case à cocher explicite sur la clé. 10 clés actives au maximum, révocation immédiate.
200 crédits au plus par 24 heures pour l'ensemble des lancements hors de l'app, réglable dans Intégrations (0 = aucun lancement).
Une seule analyse lancée par l'API ou par Claude peut tourner à la fois ; un second lancement reçoit une erreur 409.
Au-delà, la requête est refusée avec la liste des mots-clés en trop : rien n'est coupé en silence.
120 lectures et 10 écritures par minute ; suggestions : 5 par minute et 30 par jour, par compte.
Une clé ne voit que les analyses et les entreprises de son compte ; « inexistant » et « pas à vous » renvoient la même erreur 404.
Erreurs
Chaque erreur porte un code fixe, un message en anglais et l'identifiant de la requête.
Format
{ "error": { "code": "…", "message": "…", "details": { }, "request_id": "…" } }| Code | HTTP | Signification |
|---|---|---|
unauthorized | 401 | Clé absente, invalide ou révoquée. |
forbidden | 403 | Compte sans offre payante (details.reason = plan_required, avec le lien vers les offres) ou accès pas encore ouvert. |
insufficient_scope | 403 | Clé en lecture seule pour une action de lancement. |
api_disabled | 503 | API momentanément fermée. |
not_found | 404 | Ressource inexistante ou d'un autre compte. |
method_not_allowed | 405 | Méthode non permise (voir l'en-tête Allow). |
invalid_request | 422 | Paramètres invalides (détail dans details.issues). |
payload_too_large | 413 | Corps de requête supérieur à 256 Ko. |
rate_limited | 429 | Trop de requêtes (voir l'en-tête Retry-After). |
insufficient_credits | 402 | Solde de crédits insuffisant. |
daily_cap_reached | 429 | Plafond quotidien atteint. |
analysis_in_progress | 409 | Une analyse lancée hors de l'app tourne déjà. |
too_many_keywords | 422 | Plus de 200 mots-clés dans le lancement. |
max_credits_exceeded | 422 | Le coût dépasse max_credits. |
company_required | 422 | Plusieurs entreprises : précisez company_id. |
suggestion_batch_invalid | 422 | Lot de suggestions inconnu, expiré ou déjà utilisé. |
unavailable | 503 | Service momentanément indisponible : réessayez. |
internal | 500 | Erreur inattendue : communiquez le request_id au support. |
Description complète, lisible par machine : importez-la dans Postman, Insomnia ou un générateur de client.
Incluse dans toutes les offres payantes · 1 crédit = 1 mot-clé analysé