API-Dokumentation

Basis-URL für alle Endpunkte:

https://smartbrief-ai.promptingbirds.com/api/v1

Alle Anfragen und Antworten verwenden application/json (Ausnahme: der PDF-Download). Die API arbeitet ausschließlich auf Ihren eigenen Daten - exakt mit den gleichen Rechten und Limits wie Ihr Konto in der Weboberfläche.

1. Öffnen Sie Ihr Konto → Abschnitt API-Zugriff und erstellen Sie einen Key.
2. Der vollständige Key wird nur einmal angezeigt. Bewahren Sie ihn sicher auf (z. B. in einem Secret-Manager).
3. Übergeben Sie den Key bei jeder Anfrage in einem der beiden Header:

Authorization: Bearer sbk_ihr_key_hier
# oder alternativ
X-API-Key: sbk_ihr_key_hier

Sie können mehrere Keys anlegen (bis zu 10 aktive) und jeden einzeln widerrufen. Voraussetzung zum Erstellen von Berichten ist ein aktiver Plan (siehe unten); Themen und Zeitpläne funktionieren auf jedem Plan.

• Das Erstellen eines Berichts (POST /v1/topics/{id}/reports) zählt gegen Ihr monatliches Berichtskontingent Ihres Plans.
• Ist das Kontingent erschöpft oder kein aktives Abonnement vorhanden, antwortet die API mit 402 Payment Required.
• Ihren aktuellen Verbrauch fragen Sie jederzeit über GET /v1/me ab (reports_used / reports_remaining).
• Themen, Zeitpläne und weitere Verwaltungsaktionen sind nicht kontingentiert.

Schnellstart

Ein Thema anlegen und sofort einen Bericht auslösen:

# 1) Thema anlegen
curl -X POST https://smartbrief-ai.promptingbirds.com/api/v1/topics \
  -H "Authorization: Bearer sbk_ihr_key_hier" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Wettbewerber XY",
    "description": "Neuigkeiten, Produkte und Personalien",
    "schedule_interval_weeks": 1
  }'
# → { "id": 42, "name": "Wettbewerber XY", ... }

# 2) Bericht für dieses Thema erstellen
curl -X POST https://smartbrief-ai.promptingbirds.com/api/v1/topics/42/reports \
  -H "Authorization: Bearer sbk_ihr_key_hier" \
  -H "Content-Type: application/json" \
  -d '{ "timeframe_preset": "last_week" }'
# → { "id": 1337, "status": "running", ... }

# 3) Bericht abrufen (Status/Markdown)
curl https://smartbrief-ai.promptingbirds.com/api/v1/reports/1337 \
  -H "Authorization: Bearer sbk_ihr_key_hier"

Berichte werden asynchron erzeugt: Der Bericht startet mit status: "running" und wechselt später auf completed (bzw. failed). Fragen Sie den Bericht erneut ab, bis er abgeschlossen ist.

Konto & Verbrauch

{
  "email": "sie@firma.de",
  "plan": "professional",
  "reports_used": 12,
  "reports_limit": 60,
  "reports_remaining": 48,
  "period_start": "2026-06-15T00:00:00.000Z",
  "period_end": "2026-07-15T00:00:00.000Z",
  "plan_expired": false
}

Themen

Ein Thema (Topic) bündelt eine Rechercheanfrage und deren Einstellungen. Felder beim Anlegen/Ändern: name (Pflicht), description, extra_urls, report_layout, schedule_interval_weeks (0 = kein Zeitplan).

Antwort-Objekt (das Suchfeld query wird automatisch aus name + description erzeugt):

{
  "id": 42,
  "name": "Marktbeobachtung",
  "query": "Marktbeobachtung Regulatorik & Preise",
  "description": "Regulatorik & Preise",
  "extra_urls": null,
  "report_layout": null,
  "owner_email": "sie@firma.de",
  "schedule_interval_weeks": 4,
  "created_at": "2026-07-01T09:00:00.000Z",
  "updated_at": "2026-07-01T09:00:00.000Z"
}

curl -X POST https://smartbrief-ai.promptingbirds.com/api/v1/topics \
  -H "Authorization: Bearer sbk_ihr_key_hier" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Marktbeobachtung", "description": "Regulatorik & Preise", "schedule_interval_weeks": 4 }'

Berichte

Berichte werden asynchron erzeugt. Statuswerte: pending, running, completed, failed. Bei completed enthält markdown den fertigen Bericht; bei failed nennt error_message den Grund. Weitere Felder u. a.: title, topic_id, timeframe_start/timeframe_end, completed_at.

{
  "id": 1337,
  "topic_id": 42,
  "topic_name": "Wettbewerber XY",
  "status": "running",
  "timeframe_preset": "last_week",
  "created_at": "2026-07-01T09:12:00.000Z"
}

Hinweis: Berichte können über die API nicht gelöscht werden.

Automatische Zustellung

Konfigurationen für den automatischen Versand von Berichten per E-Mail. Empfänger müssen Mitglieder Ihrer Organisation sein.

curl -X POST https://smartbrief-ai.promptingbirds.com/api/v1/auto-report-configs \
  -H "Authorization: Bearer sbk_ihr_key_hier" \
  -H "Content-Type: application/json" \
  -d '{
    "topic_id": 42,
    "frequency": "weekly",
    "scheduled_day_of_week": 1,
    "scheduled_hour": 8,
    "emails": ["team@firma.de"]
  }'

• 400 - Ungültige Eingabe.
• 401 - API-Key fehlt, ist ungültig oder widerrufen.
• 402 - Kein aktives Abonnement oder Berichtskontingent erschöpft.
• 404 - Ressource nicht gefunden (oder gehört nicht Ihrem Konto).