REST paginé par curseur sur les campagnes, groupes d'annonces, annonces, mots-clés, assets, rapports et synchronisation — pour Google Ads, Microsoft Advertising, Reddit Ads et Meta Ads. Une enveloppe, des erreurs typées et une politique de versionnage écrite.
URL de base
https://api.growomat.com/api/v1
Spec
GET /api/v1/openapi.json · OpenAPI 3.1
Auth
Authorization: Bearer grow_… · 13 scopes
Limites
60 req/min par token · Retry-After sur 429
v1 · les ajouts ne cassent jamais rien · les anciennes versions tournent au moins 12 mois
première requête — GET /me
$ curl -s https://api.growomat.com/api/v1/me \ -H "Authorization: Bearer $GROWOMAT_TOKEN" { "data": { "uid": "user_abc", "email": "[email protected]", "plan": { "id": "pro" }, "scopes": ["campaigns:read", "campaigns:write"] } }
Les campagnes sont créées localement et mises en attente — aucune plateforme publicitaire n’est touchée tant qu’un token doté du scope sync ne déclenche pas de synchronisation.
Réglages → Développeur
Générez un token avec un nom, une expiration d’un an maximum et le minimum de scopes nécessaires. Le texte en clair ne s’affiche qu’une fois — seul son SHA-256 est conservé.
# shown once — store it in a secret manager grow_live_A1B2C3D4E5F6G7H8_veryLongSecret… export GROWOMAT_TOKEN=grow_live_…
Vérifier l’auth avec /me
GET /me renvoie l’identité, le plan et les scopes du token — le moyen le plus rapide de vérifier le câblage.
curl -s -H "Authorization: Bearer $GROWOMAT_TOKEN" \
https://api.growomat.com/api/v1/me
# → { "data": { "uid": "user_abc", "email": "[email protected]",
# "plan": { "id": "pro", "name": "Pro" },
# "scopes": ["campaigns:read","campaigns:write"] } }Votre première campagne en POST
Les écritures exigent le scope write de leur ressource. Chaque réponse utilise la même enveloppe : { data, meta }
curl -s -X POST https://api.growomat.com/api/v1/campaigns \
-H "Authorization: Bearer $GROWOMAT_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name":"Black Friday 2026","type":"SEARCH","budget":50}'Chaque ressource parle la même enveloppe et la même pagination par curseur. Ce que l'application peut créer, lister, modifier et supprimer — vous aussi.
| Ressource | Routes | Opérations |
|---|---|---|
| Token | /me | GET |
| Campaigns | /campaigns · /campaigns/:id | GETPOSTPATCHDELETE |
| Ad groups | /ad-groups · /ad-groups/:id | GETPOSTPATCHDELETE |
| Ads | /ads · /ads/:id | GETPOSTPATCHDELETE |
| Keywords | /keywords · /keywords/:id | GETPOSTPATCHDELETE |
| Assets | /assets · /assets/:id/attach | GETPOSTPATCHDELETE |
| Businesses | /businesses · /businesses/:id | GETPOSTPATCHDELETE |
| Reports | /reports/performance · /reports/disapprovals | GET |
| Sync | /sync · /sync/preview · /sync/:id | GETPOST |
| Conversions | /conversions/offline | GETPOST |
Les écritures exigent la portée :write de leur ressource. Une synchronisation exige en plus sync:write — c'est le seul appel qui touche les plateformes publicitaires en direct. La liste exhaustive des routes se trouve dans /api/v1/openapi.json.
Une enveloppe unique, des erreurs typées, des en-têtes de rate limit honnêtes, une pagination sans surprise et une politique de versionnage écrite.
Enveloppe de réponse— chaque endpoint
// success
{ "data": …, "meta": { "nextCursor": "1700000000", "total": 25 } }
// error — always this shape
{ "error": { "code": "INSUFFICIENT_SCOPE",
"message": "Missing required scope: campaigns:write",
"details": { "required": ["campaigns:write"] } } }Codes d’erreur— tous
| HTTP | Code | Quand |
|---|---|---|
| 400 | VALIDATION_ERROR | Corps de requête invalide |
| 401 | INVALID_CREDENTIALS | Token invalide, révoqué ou expiré |
| 402 | SUBSCRIPTION_REQUIRED · SUBSCRIPTION_EXPIRED · API_ACCESS_NOT_IN_PLAN | Facturation — à régler, puis réessayer |
| 403 | INSUFFICIENT_SCOPE | Le token n’a pas le scope requis |
| 404 | NOT_FOUND | Introuvable, ou hors du Space résolu |
| 429 | RATE_LIMITED | Limite minute ou journalière dépassée |
| 500 | INTERNAL_ERROR | Notre faute — réessayez sans risque |
Limites de débit— sur chaque réponse
| En-tête | Signification |
|---|---|
| X-RateLimit-Limit | Quota minute de ce token (60 par défaut) |
| X-RateLimit-Remaining | Requêtes restantes dans la fenêtre en cours |
| X-RateLimit-Reset | Horodatage Unix de remise à zéro de la fenêtre |
| Retry-After | Secondes à attendre, envoyé avec le 429 |
Les compteurs à la minute sont par token — un script bavard n’affame pas les autres. Le quota journalier vient de votre plan et se partage entre vos tokens.
Versionnage & Spaces— noir sur blanc
Tout vit sous /api/v1. Les ajouts — nouveaux champs, endpoints, valeurs d’énumération — sortent sans préavis et ne cassent jamais rien. Les retraits et renommages vont dans /api/v2, et les anciennes versions restent en service au moins 12 mois après l’annonce de leur remplaçante.
Envoyez l’en-tête X-Space-Id pour viser un espace de travail ; sans lui, c’est votre Space personnel. Les ids hors du Space résolu renvoient 404 — les données ne fuient jamais entre Spaces.
grow_live_A1B2C3D4E5F6G7H8_veryLongUrlSafeBase64SecretAccès par scopes — 13 autorisations
sync:write est volontairement séparé des scopes de ressources — déclencher une synchronisation modifie les plateformes publicitaires externes et peut dépenser un vrai budget. Un token de reporting n’en a jamais besoin.
La création de jetons est dans Paramètres → Développeur. Vous préférez un client typé ? Les SDK sont générés depuis la spécification de cette API.