Cursor-paginiertes REST über Kampagnen, Anzeigengruppen, Anzeigen, Keywords, Assets, Berichte und Synchronisierung — für Google Ads, Microsoft Advertising, Reddit Ads und Meta Ads. Ein Umschlag, typisierte Fehler und eine schriftlich festgehaltene Versionierungsrichtlinie.
Basis-URL
https://api.growomat.com/api/v1
Spec
GET /api/v1/openapi.json · OpenAPI 3.1
Auth
Authorization: Bearer grow_… · 13 Scopes
Limits
60 Req/Min pro Token · Retry-After bei 429
v1 · additive Änderungen sind nie brechend · alte Versionen laufen mindestens 12 Monate weiter
erste Anfrage — 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"] } }
Kampagnen werden lokal erstellt und bereitgestellt — keine Live-Werbeplattform wird angefasst, bis ein Token mit Sync-Scope einen Sync auslöst.
Einstellungen → Developer
Erstellen Sie ein Token mit Namen, einer Laufzeit von bis zu einem Jahr und den minimal nötigen Scopes. Der Klartext erscheint genau einmal — gespeichert wird nur der SHA-256.
# shown once — store it in a secret manager grow_live_A1B2C3D4E5F6G7H8_veryLongSecret… export GROWOMAT_TOKEN=grow_live_…
Auth mit /me prüfen
GET /me liefert Identität, Plan und Scopes des Tokens zurück — der schnellste Beleg, dass alles verdrahtet ist.
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"] } }Erste Kampagne per POST
Schreibzugriffe brauchen den Write-Scope ihrer Ressource. Jede Response nutzt denselben Envelope: { 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}'Jede Ressource spricht denselben Umschlag und dieselbe Cursor-Paginierung. Was die App anlegen, auflisten, bearbeiten und löschen kann, können Sie auch.
| Ressource | Routen | Operationen |
|---|---|---|
| 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 |
Schreibzugriffe brauchen den :write-Scope ihrer Ressource. Eine Synchronisierung braucht zusätzlich sync:write — sie ist der einzige Aufruf, der Live-Werbeplattformen berührt. Die vollständige Routenliste steht in /api/v1/openapi.json.
Ein Envelope, typisierte Fehler, ehrliche Rate-Limit-Header, unaufgeregte Paginierung und eine schriftliche Versionierungs-Policy.
Response-Envelope— jeder Endpunkt
// 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"] } } }Fehlercodes— alle
| HTTP | Code | Wann |
|---|---|---|
| 400 | VALIDATION_ERROR | Ungültiger Request-Body |
| 401 | INVALID_CREDENTIALS | Ungültiges, widerrufenes oder abgelaufenes Token |
| 402 | SUBSCRIPTION_REQUIRED · SUBSCRIPTION_EXPIRED · API_ACCESS_NOT_IN_PLAN | Abrechnung — klären, dann erneut versuchen |
| 403 | INSUFFICIENT_SCOPE | Dem Token fehlt der nötige Scope |
| 404 | NOT_FOUND | Nicht vorhanden oder außerhalb des aufgelösten Space |
| 429 | RATE_LIMITED | Minuten- oder Tageslimit überschritten |
| 500 | INTERNAL_ERROR | Unser Fehler — Retry ist sicher |
Rate-Limits— in jeder Response
| Header | Bedeutung |
|---|---|
| X-RateLimit-Limit | Minuten-Bucket dieses Tokens (Standard 60) |
| X-RateLimit-Remaining | Verbleibende Requests im aktuellen Fenster |
| X-RateLimit-Reset | Unix-Zeitpunkt, an dem das Fenster zurückgesetzt wird |
| Retry-After | Wartezeit in Sekunden, gesendet mit 429 |
Minuten-Buckets gelten pro Token — ein lautes Skript verdrängt kein anderes. Das Tages-Budget kommt aus Ihrem Plan und gilt über alle Tokens hinweg.
Versionierung & Spaces— schriftlich
Alles lebt unter /api/v1. Ergänzungen — neue Felder, Endpunkte, Enum-Werte — erscheinen ohne Ankündigung und sind nie Breaking. Entfernungen und Umbenennungen wandern nach /api/v2, und alte Versionen laufen mindestens 12 Monate nach Ankündigung des Nachfolgers weiter.
Senden Sie den X-Space-Id-Header, um einen Workspace zu adressieren; ohne Header gilt Ihr Personal Space. IDs außerhalb des aufgelösten Space liefern 404 — Daten fließen nie zwischen Spaces.
grow_live_A1B2C3D4E5F6G7H8_veryLongUrlSafeBase64SecretScoped Access — 13 Berechtigungen
sync:write ist bewusst von den Ressourcen-Scopes getrennt — ein Sync verändert externe Werbeplattformen und kann echtes Budget ausgeben. Ein Reporting-Token braucht ihn nie.
Tokens erstellen Sie unter Einstellungen → Entwickler. Lieber ein typisierter Client? Die SDKs werden aus der Spezifikation dieser API generiert.