# CampaignKit API

> Middleware vor der Meta Marketing API. Einheitliche, versionierte Requests; 
> der API-Key bestimmt den Meta-Account, der Meta-Token verlässt nie den Server.

Base URL: https://api.campaignkit.ventureon.io/v1
Docs: https://docs.campaignkit.ventureon.io
Auth: Authorization: Bearer <API-Key>
Version: v1 (gepinnt auf Meta v25.0)

## Guides
- Einführung (https://docs.campaignkit.ventureon.io/docs#einfuehrung)
- Quickstart (https://docs.campaignkit.ventureon.io/docs#quickstart)
- Auth & Header (https://docs.campaignkit.ventureon.io/docs#auth)
- Konventionen (https://docs.campaignkit.ventureon.io/docs#konventionen)
- Fehler (https://docs.campaignkit.ventureon.io/docs#fehler)
- Plan-Gating (https://docs.campaignkit.ventureon.io/docs#plan-gating)
- Webhooks (https://docs.campaignkit.ventureon.io/docs#webhooks)
- Versionierung (https://docs.campaignkit.ventureon.io/docs#versionierung)

## Endpoints

### System
Verbindung & Health. Der einzige bereits implementierte Endpunkt — prüft API-Key und Erreichbarkeit.
- GET /v1/health — Authentifizierter Health-Check

### Media
Übergibt fertige Bild und Video-Assets per URL an Meta und liefert die Referenz (image_hash bzw. video_id) für Creatives. Wir komprimieren NICHT und speichern die Datei nicht. Der Kunde ist für Format, Größe, Kompression und Versionierung selbst zuständig und übergibt nur die finale, öffentlich erreichbare URL.
- POST /v1/media/images — Bild von URL → image_hash
- GET /v1/media/images — Bilder aus Meta auflisten
- POST /v1/media/videos — Video von URL → video_id (async)
- GET /v1/media/videos — Videos aus Meta auflisten
- GET /v1/media/videos/{id} — Video-Verarbeitungsstatus pollen

### Ad Sets
Oberste für dich sichtbare Ebene (Ad Set → Ad). Beim Anlegen referenzierst du über `target` (Ziel-Schlüssel) das von uns eingerichtete Ziel — die übergeordnete Kampagne und ihre Konfiguration verwalten wir für dich. Du lieferst nur Budget/Laufzeit und optional Alter/Geschlecht/Interessen — Optimierung, Platzierung, Geo, Abrechnung, DSA und der Name kommen verbindlich aus der hinterlegten Konfiguration.
- POST /v1/adsets — Ad Set anlegen (Budget + Laufzeit)
- GET /v1/adsets — Ad Sets lesen
- PATCH /v1/adsets/{id} — Ändern
- DELETE /v1/adsets/{id} — Archivieren

### Creatives
Visuelles Asset (Bild ODER Video) + Text, Link und Call-to-Action. Die Absender-Identität (Facebook-Page, optional Instagram) kommt aus der Kunden-Konfiguration — nicht aus dem Request.
- POST /v1/creatives — Medium als Creative-Entwurf registrieren
- GET /v1/creatives — Creatives lesen
- PATCH /v1/creatives/{id} — Ändern
- DELETE /v1/creatives/{id} — Archivieren

### Templates
Zwei Wege: (1) VORLAGEN ANZEIGEN — GET /v1/templates liefert je Vorlage bereits fertige, gecachte `preview_urls` (je Format), die du unverändert direkt als Bild einbettest (img-Tag). Kein eigenes Rendern nötig, kein API-Key in der Bild-URL. (2) EIGENES CREATIVE — GET /v1/templates/{id} (Felder lesen) + POST /v1/templates/render (eigene Inhalte) erzeugt ein Werbemittel für POST /v1/ads.
- GET /v1/templates — Zugewiesene Vorlagen auflisten
- GET /v1/templates/{id} — Parameter-Schema einer Vorlage (für KI)
- GET /v1/templates/{id}/preview — Hinterlegte Vorschau-Parameter lesen
- GET /v1/templates/{id}/preview.png — Vorschau-Bild (öffentlich, direkt einbettbar)
- POST /v1/templates/render — Vorlage rendern (Creative-Entwurf, nur Visual)
- GET /v1/templates/render/{id} — Status eines Video-Renders pollen

### Ads
Verknüpft Ad Set + Creative zur fertigen Anzeige. Der Name wird automatisch vergeben (Naming Convention); die Ad startet als PAUSED-Entwurf.
- POST /v1/ads — Anzeige einstellen + ausspielen
- GET /v1/ads — Ads inkl. Review-Status lesen
- PATCH /v1/ads/{id} — Ändern
- DELETE /v1/ads/{id} — Archivieren

### Audiences
Custom Audiences aus rohen CRM-Kontakten (serverseitig gehasht) und darauf basierende Lookalikes.
- GET /v1/audiences — Audiences auflisten
- POST /v1/audiences/custom — Custom Audience aus CRM
- POST /v1/audiences/lookalike — Lookalike aus Custom Audience
- GET /v1/audiences/{id} — Detail und Live-Status
- PATCH /v1/audiences/{id} — Name/Beschreibung ändern
- DELETE /v1/audiences/{id} — Löschen
- POST /v1/audiences/{id}/contacts — Kontakte hinzufügen
- DELETE /v1/audiences/{id}/contacts — Kontakte entfernen

### Targeting
Lookup-Helfer, um gültige Geo- und Interessen-Keys für das Targeting zu finden.
- GET /v1/targeting/geo?q= — Stadt-Lookup (DACH City-Keys)
- GET /v1/targeting/interests?q= — Interessen-Lookup

### Reporting
Normalisierte Performance-Metriken aus täglich gesyncten Snapshots. Die Kundenplattform verknüpft sie mit eigenen Verkaufsdaten.
- GET /v1/insights — Metriken: level, entity_id, adset_id, date_range, fields, breakdowns

### Status / Webhooks
Review-/Lieferstatus live abfragen (Pull) oder per registrierter Webhook-URL empfangen (Push).
- GET /v1/status/{ad_id} — Live effective_status
- GET /v1/webhooks — Registrierte Webhooks lesen
- POST /v1/webhooks — Webhook-URL registrieren

### Plan & Abrechnung
Vertragszustand und voraussichtliche Gebühr lesen, Konto selbst deaktivieren und jederzeit an die Rechnungen kommen. Es gibt keine Tarifwahl: die Stufe ergibt sich rückwirkend aus dem realen Ad-Spend.
- GET /v1/plan — Zustand + Stufe + voraussichtliche Gebühr
- GET /v1/plan/usage — Laufender Zyklus + Spend + Projektion
- POST /v1/account/deactivate — Konto deaktivieren (0 €)