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 Passer, 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). |
| POST | /api/v1/companies | Crée la fiche d'un compte entreprise qui n'en a pas, ou un nouveau client d'agence (doublons refusés). |
| GET | /api/v1/companies/{company_id} | Fiche entreprise complète (textes, concurrents, produits avec tous leurs champs) et règles de modification du compte. |
| POST | /api/v1/companies/{company_id} | Modifie seulement les champs envoyés (null = vider) ; rien d'autre n'est écrasé. |
| POST | /api/v1/companies/{company_id}/delete | Supprime un client d'agence qui n'a aucune analyse. La fiche d'un compte entreprise ne se supprime pas. |
| POST | /api/v1/companies/{company_id}/products | Ajoute un produit à une fiche (20 au plus, même nom refusé). |
| POST | /api/v1/companies/{company_id}/products/{product_id} | Modifie seulement les champs du produit envoyés. |
| POST | /api/v1/companies/{company_id}/products/{product_id}/delete | Supprime un produit (refusé pendant une analyse qui le vise) ; les analyses terminées gardent leurs résultats. |
| 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 ; lancer des analyses et modifier les fiches sont deux cases à cocher explicites 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).
Jusqu'à 5 analyses lancées par l'API ou par Claude peuvent tourner en même temps ; une place se libère dès que tous les mots-clés d'une analyse ont leur résultat. Au-delà, le lancement reçoit une erreur 409 qui liste les analyses en cours.
Au-delà, la requête est refusée avec la liste des mots-clés en trop : rien n'est coupé en silence.
300 requêtes par minute au total, dont 120 lectures et 10 écritures par minute ; suggestions : 5 par minute et 30 par jour, par compte. Chaque réponse annonce la règle et ce qu'il reste dans les en-têtes RateLimit-Policy et RateLimit ; un refus 429 donne le délai d'attente dans Retry-After.
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, ou sans le droit « Modifier les fiches » pour une écriture de fiche. |
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. |
concurrency_limit_reached | 409 | Limite d'analyses en parallèle atteinte (details.active_analyses liste celles en cours). |
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é. |
conflict | 409 | Conflit avec l'état de la fiche (details.reason) : fiche déjà créée, client ou produit en double, client avec des analyses, produit en cours d'analyse, modification simultanée. |
limit_reached | 422 | Limite atteinte : 20 produits par fiche au plus. |
unavailable | 503 | Service momentanément indisponible : réessayez. |
internal | 500 | Erreur inattendue : communiquez le request_id au support. |
Versions
La version est dans l'adresse (/api/v1) : ce qui fonctionne aujourd'hui continue de fonctionner.
Dans la v1, on ajoute (nouvelles routes, nouveaux paramètres facultatifs, nouveaux champs dans les réponses) ; on ne retire ni ne renomme rien. Votre code doit ignorer les champs qu'il ne connaît pas.
Un changement qui casserait un script existant passe par une nouvelle version (/api/v2). La v1 reste en service au moins 6 mois après l'annonce de la nouvelle version.
Avant tout retrait, la route ou le champ est marqué deprecated dans la spec OpenAPI, ses réponses portent les en-têtes Deprecation et Sunset avec les dates, et le changement est annoncé sur cette page.
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é