Content Autopilot API

Schnellstart

Integrationsablauf

Die Integration folgt einem Push- und Pull-Muster. Webhooks informieren dein System über neue Artikel, die Pull API liefert den vollständigen Inhalt.

Schritt 1: Artikel wird im Visibly Content Autopilot freigegeben
   |
   v
Schritt 2: Webhook feuert an deinen Endpunkt
   POST https://your-cms.com/webhooks/visibly
   Headers:
     Content-Type: application/json
     X-Webhook-Signature: sha256=<hmac_digest>
     X-Webhook-Event: article.approved
     User-Agent: VisiblyAI-Webhook/1.0
   Body:
     {
       "event": "article.approved",
       "article_id": 42,
       "title": "SEO Guide 2026",
       "slug": "seo-guide-2026",
       "project_id": 5,
       "scheduled_date": "2026-03-01T09:00:00",
       "pull_url": "https://app.visibly-ai.com/api/v1/articles/42",
       "timestamp": "2026-02-20T10:00:00Z"
     }
   |
   v
Schritt 3: Dein Handler verifiziert die HMAC-SHA256-Signatur
   Vergleiche X-Webhook-Signature mit HMAC(secret, raw_body)
   Bei Abweichung mit 401 ablehnen
   |
   v
Schritt 4: Dein Handler ruft die Pull API für den vollständigen Inhalt auf
   GET /api/v1/articles/42?include_markdown=true
   Authorization: Bearer cp_your_project_key
   |
   v
Schritt 5: Dein CMS speichert/veröffentlicht den Artikel
   scheduled_date für die Planung, content_html für das Rendering
   |
   v
Schritt 6: Dein Handler bestätigt die Veröffentlichung
   POST /api/v1/articles/42/confirm
   Authorization: Bearer cp_your_project_key
   Body: {"published_url": "https://your-cms.com/blog/seo-guide-2026"}
   |
   v
Fertig. Der Artikel-Status wechselt in Visibly auf "published".

Authentifizierung

Alle API-Anfragen erfordern einen Bearer-Token im Authorization-Header:

Authorization: Bearer cp_your_project_key

Zwei Key-Arten am selben Gate

Artikel-Lebenszyklus

Jeder Artikel durchläuft folgende Status-Phasen:

Der typische Flow für CMS-Integrationen: Du filterst die Pull API nach status=approved oder empfängst den article.approved-Webhook, holst den Artikel ab und bestätigst dann mit dem confirm-Endpunkt.

Pull API Endpunkte

Basis-URL: https://app.visibly-ai.com

GET/api/v1/articles

Listet Artikel mit optionalen Filtern auf. Ergebnisse sind nach Erstellungsdatum absteigend sortiert.

# Alle freigegebenen Artikel des Projekts 5 auflisten
curl -H "Authorization: Bearer cp_your_project_key" \
  "https://app.visibly-ai.com/api/v1/articles?status=approved&project_id=5&limit=10"

// Antwort (200 OK)
{
  "articles": [
    {
      "id": 42,
      "title": "SEO Guide 2026",
      "slug": "seo-guide-2026",
      "status": "approved",
      "word_count": 1850,
      "seo_score": 85,
      "meta_description": "Learn how to optimize your website for search engines in 2026.",
      "project_id": 5,
      "plan_id": 12,
      "recommended_page_type": "guide",
      "url_prefix": "/ratgeber/seo/",
      "published_url": "",
      "scheduled_date": "2026-03-01T09:00:00",
      "created_at": "2026-02-20T10:00:00",
      "updated_at": "2026-02-20T12:00:00"
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

GET/api/v1/articles/{id}

Ruft einen einzelnen Artikel mit vollständigem Inhalt ab. Gibt HTML-Inhalt immer zurück. Markdown-Inhalt nur auf Anfrage.

# Artikel 42 mit vollständigem Markdown-Inhalt abrufen
curl -H "Authorization: Bearer cp_your_project_key" \
  "https://app.visibly-ai.com/api/v1/articles/42?include_markdown=true"

// Antwort (200 OK)
{
  "article": {
    "id": 42,
    "title": "SEO Guide 2026",
    "slug": "seo-guide-2026",
    "status": "approved",
    "word_count": 1850,
    "seo_score": 85,
    "meta_description": "Learn how to optimize your website for search engines in 2026.",
    "content_html": "<h1>SEO Guide 2026</h1>\n<p>Search engine optimization is...</p>",
    "content_markdown": "# SEO Guide 2026\n\nSearch engine optimization is...",
    "keywords": ["seo", "search engine optimization", "keyword research"],
    "project_id": 5,
    "plan_id": 12,
    "recommended_page_type": "guide",
    "url_prefix": "/ratgeber/seo/",
    "published_url": "",
    "scheduled_date": "2026-03-01T09:00:00",
    "cms_published_at": null,
    "created_at": "2026-02-20T10:00:00",
    "updated_at": "2026-02-20T12:00:00"
  }
}

POST/api/v1/articles/{id}/confirm

Bestätigt, dass der Artikel extern veröffentlicht wurde. Dieser Endpunkt ist idempotent: Ein erneuter Aufruf auf einen bereits veröffentlichten Artikel gibt Erfolg zurück.

# Veröffentlichung mit der Live-URL bestätigen
curl -X POST -H "Authorization: Bearer cp_your_project_key" \
  -H "Content-Type: application/json" \
  -d '{"published_url": "https://myblog.com/seo-guide-2026"}' \
  "https://app.visibly-ai.com/api/v1/articles/42/confirm"

// Antwort (200 OK) - erste Bestätigung
{
  "success": true,
  "article_id": 42,
  "message": null
}

// Antwort (200 OK) - bereits veröffentlicht (idempotent)
{
  "success": true,
  "article_id": 42,
  "message": "Article already confirmed as published"
}

Feld-Referenz

Vollständige Auflistung aller Felder in API-Antworten.

Artikel-Felder (Liste und Einzelabruf)

Zusätzliche Felder (nur Einzelabruf GET /articles/{id})

Pagination-Felder (nur Liste GET /articles)

Webhook-Events

Webhooks werden bei Statusänderungen ausgelöst. Du konfigurierst sie pro CMS-Zugang im Projekt unter dem Werkzeug Content Autopilot > CMS-Zugänge. Dort trägst du deine Webhook-URL und ein selbst gewähltes, geteiltes HMAC-Secret ein (kein Auto-generierter Wert, du hinterlegst dasselbe Secret auf beiden Seiten) und wählst die Events aus, die du empfangen willst.

Webhook-Payload

Jeder Webhook sendet folgendes JSON als POST-Body:

{
  "event": "article.approved",
  "article_id": 42,
  "title": "SEO Guide 2026",
  "slug": "seo-guide-2026",
  "project_id": 5,
  "scheduled_date": "2026-03-01T09:00:00",
  "pull_url": "https://app.visibly-ai.com/api/v1/articles/42",
  "timestamp": "2026-02-20T10:00:00Z"
}

Webhook-HTTP-Headers

Webhook-Zustellung

Details zur Webhook-Zustellung:

HMAC-SHA256 Verifizierung

Jeder Webhook wird mit einer HMAC-SHA256-Signatur im Header X-Webhook-Signature gesendet. Verifiziere die Signatur, um sicherzustellen, dass der Webhook von Visibly stammt und nicht manipuliert wurde.

Algorithmus:

1. Lies den rohen Request-Body als Bytes, nicht als String
2. Berechne HMAC-SHA256(webhook_secret, raw_body)
3. Vergleiche das Ergebnis als sha256=<hex_digest> mit dem Header-Wert
4. Verwende einen timing-safe Vergleich, z.B. hmac.compare_digest, um Timing-Attacks zu verhindern

Python

import hmac, hashlib

def verify_signature(payload_bytes, secret, signature):
    """Verify HMAC-SHA256 webhook signature.

    Args:
        payload_bytes: Raw request body as bytes
        secret: Your webhook secret (string)
        signature: Value of X-Webhook-Signature header

    Returns:
        True if signature is valid
    """
    if not signature or not signature.startswith('sha256='):
        return False
    expected = f"sha256={hmac.new(secret.encode('utf-8'), payload_bytes, hashlib.sha256).hexdigest()}"
    return hmac.compare_digest(expected, signature)

# In deiner Flask-Route:
payload = request.get_data()  # rohe Bytes, NICHT request.json
sig = request.headers.get('X-Webhook-Signature', '')
if not verify_signature(payload, WEBHOOK_SECRET, sig):
    return jsonify({'error': 'Invalid signature'}), 401

Node.js

const crypto = require('crypto');

function verifySignature(payload, secret, signature) {
  if (!signature || !signature.startsWith('sha256=')) return false;
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(signature)
  );
}

// Express mit raw body parser:
// app.use('/webhooks', express.raw({ type: 'application/json' }))
app.post('/webhooks/visibly', (req, res) => {
  const sig = req.headers['x-webhook-signature'] || '';
  if (!verifySignature(req.body, process.env.WEBHOOK_SECRET, sig)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const data = JSON.parse(req.body);
  const { article_id, scheduled_date, pull_url } = data;

  // Vollständigen Artikel von pull_url abrufen...
  res.json({ success: true });
});

PHP

function verifySignature($payload, $secret, $signature) {
    if (!$signature || strpos($signature, 'sha256=') !== 0) return false;
    $expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);
    return hash_equals($expected, $signature);
}

$payload = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
if (!verifySignature($payload, $webhookSecret, $sig)) {
    http_response_code(401);
    echo json_encode(['error' => 'Invalid signature']);
    exit;
}

$data = json_decode($payload, true);
$articleId = $data['article_id'];
$scheduledDate = $data['scheduled_date'] ?? null;

// Vollständigen Artikel über die Pull API abrufen...

Rate Limits

Richtwerte: Diese Grenzen beschreiben die vorgesehene Auslastung; eine harte Durchsetzung kann auf Infrastruktur-Ebene erfolgen und sich ändern.

Bei Überschreitung erhältst du HTTP 429 mit einem Retry-After Header. Warte die angegebene Anzahl Sekunden, bevor du die Anfrage wiederholst.

Fehler-Antworten

Alle Fehler werden als JSON mit einem detail-Feld zurückgegeben:

{
  "detail": "Human-readable error description"
}

Vollständiges Integrationsbeispiel

Dieser Code zeigt eine produktionsreife Integration. Kopiere ihn als Ausgangspunkt für dein CMS.

Flask (Python)

import hmac, hashlib, json, logging, requests
from flask import Flask, request, jsonify

app = Flask(__name__)
logger = logging.getLogger(__name__)

# Konfiguration - durch deine echten Zugangsdaten ersetzen
WEBHOOK_SECRET = 'dein-webhook-secret-aus-den-cms-zugangs-einstellungen'
API_KEY = 'cp_dein_projekt_key'
BASE_URL = 'https://app.visibly-ai.com'


def verify_signature(payload_bytes, secret, signature):
    """Verify HMAC-SHA256 webhook signature."""
    if not signature or not signature.startswith('sha256='):
        return False
    expected = f"sha256={hmac.new(secret.encode('utf-8'), payload_bytes, hashlib.sha256).hexdigest()}"
    return hmac.compare_digest(expected, signature)


def fetch_article(article_id):
    """Fetch full article from Pull API."""
    url = f'{BASE_URL}/api/v1/articles/{article_id}?include_markdown=true'
    resp = requests.get(url, headers={'Authorization': f'Bearer {API_KEY}'}, timeout=30)
    resp.raise_for_status()
    return resp.json()['article']


def confirm_published(article_id, published_url):
    """Confirm article was published."""
    url = f'{BASE_URL}/api/v1/articles/{article_id}/confirm'
    resp = requests.post(url,
        headers={'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'},
        json={'published_url': published_url},
        timeout=30)
    return resp.status_code == 200


def save_to_cms(article, scheduled_date):
    """Save article to your CMS. Replace with your actual CMS logic."""
    post = {
        'title': article['title'],
        'slug': article['slug'],
        'body_html': article['content_html'],
        'body_markdown': article.get('content_markdown', ''),
        'meta_description': article['meta_description'],
        'keywords': article['keywords'],
        'publish_at': scheduled_date,  # null = sofort veröffentlichen
    }
    # db.session.add(Post(**post))
    # db.session.commit()
    logger.info(f"Saved article: {article['title']}")
    return f"https://myblog.com/blog/{article['slug']}"


@app.route('/webhooks/visibly', methods=['POST'])
def handle_webhook():
    # Schritt 1: HMAC-Signatur verifizieren
    payload = request.get_data()
    sig = request.headers.get('X-Webhook-Signature', '')
    if not verify_signature(payload, WEBHOOK_SECRET, sig):
        return jsonify({'error': 'Invalid signature'}), 401

    # Schritt 2: Webhook-Payload parsen
    data = json.loads(payload)
    event = data['event']
    article_id = data['article_id']
    scheduled_date = data.get('scheduled_date')  # ISO-String oder null

    # Schritt 3: Nur article.approved verarbeiten
    if event != 'article.approved':
        return jsonify({'success': True, 'message': 'Event ignored'})

    # Schritt 4: Vollständigen Artikel über die Pull API abrufen
    article = fetch_article(article_id)

    # Schritt 5: Im CMS speichern
    published_url = save_to_cms(article, scheduled_date)

    # Schritt 6: Veröffentlichung bestätigen
    confirm_published(article_id, published_url)

    return jsonify({'success': True, 'article_id': article_id})

Node.js (Express)

const express = require('express');
const crypto = require('crypto');
const axios = require('axios');

const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;
const API_KEY = process.env.VISIBLY_API_KEY;
const BASE_URL = 'https://app.visibly-ai.com';

// WICHTIG: raw body parser für die HMAC-Verifizierung
app.use('/webhooks', express.raw({ type: 'application/json' }));

function verifySignature(payload, secret, signature) {
  if (!signature || !signature.startsWith('sha256=')) return false;
  const expected = 'sha256=' +
    crypto.createHmac('sha256', secret).update(payload).digest('hex');
  try {
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
  } catch {
    return false;
  }
}

app.post('/webhooks/visibly', async (req, res) => {
  // Schritt 1: Signatur verifizieren
  const sig = req.headers['x-webhook-signature'] || '';
  if (!verifySignature(req.body, WEBHOOK_SECRET, sig)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Schritt 2: Payload parsen
  const data = JSON.parse(req.body);
  const { event, article_id, scheduled_date } = data;

  if (event !== 'article.approved') {
    return res.json({ success: true, message: 'Event ignored' });
  }

  // Schritt 3: Vollständigen Artikel abrufen
  const { data: articleResp } = await axios.get(
    `${BASE_URL}/api/v1/articles/${article_id}?include_markdown=true`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  const article = articleResp.article;

  // Schritt 4: Im eigenen CMS speichern
  const publishedUrl = await saveToCms(article, scheduled_date);

  // Schritt 5: Veröffentlichung bestätigen
  await axios.post(
    `${BASE_URL}/api/v1/articles/${article_id}/confirm`,
    { published_url: publishedUrl },
    { headers: { Authorization: `Bearer ${API_KEY}`, 'Content-Type': 'application/json' } }
  );

  res.json({ success: true, article_id });
});

app.listen(3000);

Python SDK (ContentPilot Integration)

Wir stellen ein fertiges Python-Modul bereit, das du direkt in deine Flask-Anwendung integrieren kannst. Es enthält einen Pull-API-Client, HMAC-Verifizierung und einen Flask-Blueprint als Webhook-Empfänger.

Verwendung

# pip install ai-content-autopilot
from ai_content_autopilot import (
    contentpilot_webhook_bp,
    configure_visibly,
    VisiblyClient,
    verify_webhook_signature,
)

# --- Option A: Vollständiger Blueprint (Webhook-Empfänger + Auto-Fetch) ---

def my_article_handler(article):
    """Called when a webhook delivers an article.

    Args:
        article: dict with all article fields + webhook metadata:
            - id, title, slug, content_html, content_markdown
            - keywords, meta_description, seo_score, word_count
            - scheduled_date, cms_published_at
            - _webhook_event (e.g. "article.approved")
            - _webhook_timestamp
            - _scheduled_date (from webhook payload)

    Returns:
        True if successfully processed
    """
    # In deiner Datenbank, CMS oder Dateisystem speichern
    db.session.add(Post(
        title=article['title'],
        body=article['content_html'],
        publish_at=article.get('_scheduled_date'),
    ))
    db.session.commit()
    return True

configure_visibly(
    webhook_secret='dein-webhook-secret',
    api_key='cp_dein_projekt_key',
    base_url='https://app.visibly-ai.com',
    on_article_received=my_article_handler,
)
app.register_blueprint(contentpilot_webhook_bp)
# POST /webhooks/visibly erledigt danach automatisch:
# 1. HMAC-Signatur verifizieren
# 2. Vollständigen Artikel über die Pull API abrufen
# 3. my_article_handler(article) aufrufen
# 4. {"success": true} oder einen Fehler zurückgeben


# --- Option B: Eigenständiger Pull-API-Client ---

client = VisiblyClient(
    api_key='cp_dein_projekt_key',
    base_url='https://app.visibly-ai.com',
    timeout=30,
)

# Freigegebene Artikel auflisten
articles = client.list_articles(status='approved', project_id=5, limit=20)
for a in articles:
    print(a['id'], a['title'], a['scheduled_date'])

# Einzelnen Artikel mit vollständigem Inhalt abrufen
article = client.fetch_article(42, include_markdown=True)
print(article['content_html'])
print(article['keywords'])

# Veröffentlichung bestätigen
success = client.confirm_published(42, 'https://myblog.com/seo-guide-2026')


# --- Option C: Nur HMAC-Verifizierung ---

payload_bytes = request.get_data()
signature = request.headers.get('X-Webhook-Signature', '')
is_valid = verify_webhook_signature(payload_bytes, 'dein-secret', signature)

API-Referenz