Toon Klusio blogs op je eigen website

Wat gebeurt er precies?

Snelle start

1. Maak ingelogd een API-key aan bij Instellingen → API.
2. Kopieer de key meteen; Klusio toont hem maar één keer volledig.
3. Laat je website de key op de server meesturen.
4. Vraag eerst één artikel op en controleer daarna de vormgeving.

Basisadres

Eerste test met cURL

curl --request GET \
  --url "https://klusio.nl/api/v1/blogs?company_id=JOUW_BEDRIJFS_ID&limit=1" \
  --header "X-API-Key: JOUW_API_KEY"

Een geslaagde request geeft HTTP-status 200 en begint met {"success":true.

API-key veilig gebruiken

Een API-key werkt als een wachtwoord voor de koppeling. Stuur hem bij voorkeur mee met de header X-API-Key. Een Bearer-header wordt ook ondersteund.

X-API-Key: JOUW_API_KEY

# Alternatief
Authorization: Bearer JOUW_API_KEY

• Geef iedere website of koppeling een eigen key met een herkenbare naam.
• Schakel een key uit wanneer een koppeling tijdelijk stopt.
• Verwijder en vervang een key die mogelijk is uitgelekt.
• Gebruik een vervaldatum voor tijdelijke externe toegang.

Welke gegevens kun je opvragen?

Gebruik per request één hoofdkeuze: een lijst, één artikel, een topic, een pillar of gerelateerde artikelen. Combineer slug, topic_id, pillar_url en related_to niet; de API weigert zo'n dubbelzinnige request met HTTP 400.

Parameters voor lijsten

Zo ziet een response eruit

Lijst met artikelen

{
  "success": true,
  "total": 75,
  "limit": 1,
  "offset": 0,
  "posts": [{
    "id": 2042,
    "slug": "voorbeeld-artikel",
    "title": "Voorbeeldtitel",
    "meta_description": "Korte omschrijving voor Google.",
    "featured_image": "https://voorbeeld.nl/afbeelding.webp",
    "featured_image_alt": "Beschrijving van de afbeelding",
    "author": "Naam auteur",
    "published_at": "2026-08-12 09:00:00",
    "reading_time": 6,
    "views_count": 123,
    "is_indexed": true,
    "content_type": "how_to_guide"
  }],
  "reviews": {
    "google_rating": 4.8,
    "total_reviews": 47,
    "rating_distribution": {"5":42,"4":3,"3":1,"2":0,"1":1},
    "business_name": "Voorbeeldbedrijf",
    "latest_reviews": []
  },
  "filters_applied": {
    "search": null,
    "sort": "recent",
    "visibility": {"min_views":0,"require_indexed":false,"hide_after_days":null}
  }
}

De lijst bevat bewust geen volledige artikeltekst. Vraag een artikel daarna op via slug.

Eén volledig artikel

De single-post response bevat post met onder andere content, meta_description, featured_image, cta_text, cta_link, topicvelden en eventuele FAQ-, HowTo- en claimdata. Daarnaast krijg je:

• author_details en reviewer_details voor zichtbare expertiseblokken;
• schema_markup en seo_head voor correcte SEO-uitvoer;
• pillar_post wanneer het artikel aan een hoofdpagina is gekoppeld;
• tracking_script en tracking_token voor veilige paginameting;
• reviews met de laatst gesynchroniseerde Google Reviews.

Compleet PHP-voorbeeld

Dit voorbeeld haalt op de server vijf blogs op. De API-key staat in een environment variable en komt dus niet in de browser terecht.

<?php
$apiKey = getenv('KLUSIO_API_KEY');
$url = 'https://klusio.nl/api/v1/blogs?company_id=JOUW_BEDRIJFS_ID&limit=5&sort=recent';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        'Accept: application/json',
        'X-API-Key: ' . $apiKey,
    ],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);

if ($body === false || $curlError !== '') {
    throw new RuntimeException('Klusio API is niet bereikbaar: ' . $curlError);
}

$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status !== 200 || empty($data['success'])) {
    throw new RuntimeException($data['error'] ?? 'Onbekende API-fout');
}

foreach ($data['posts'] as $post) {
    echo '<a href="/blog/' . rawurlencode($post['slug']) . '">';
    echo htmlspecialchars($post['title'], ENT_QUOTES, 'UTF-8');
    echo '</a>';
}

Artikelweergaven meten

Vraag je één artikel via slug op, dan levert Klusio een kant-en-klaar tracking_script. Dat script gebruikt een kortlevend token dat alleen bij dat artikel en bedrijf past.

// Na een geslaagde single-post request:
echo $data['post']['content'];
echo $data['tracking_script']; // bij voorkeur vlak voor </body>

Voor een eigen implementatie stuur je een POST naar https://klusio.nl/api/v1/track met post_id, company_id en de ontvangen tracking_token. Optioneel zijn visitor_id, time_spent, scroll_depth, referrer en converted.

Herkenbaar AI-verkeer meten

De Klusio-embed en WordPress-plugin doen dit automatisch. Voor een eigen serverkoppeling gebruik je POST /api/v1/ai-traffic. Stuur de API-key via X-API-Key. Klusio accepteert alleen herkenbare AI-referrals en AI-user-agents; een gewone Googlebot, Bingbot of zoekmachinereferral telt niet als AI.

{
  "event_type": "crawler",
  "event_key": "unieke-idempotency-key-per-request",
  "landing_url": "https://voorbeeld.nl/dienstpagina",
  "user_agent": "OAI-SearchBot/1.0"
}

Google Reviews

Responses bevatten het laatst gesynchroniseerde reviewoverzicht: gemiddelde beoordeling, aantal reviews, verdeling per ster, bedrijfsnaam en maximaal tien zichtbare recente reviews. Deze gegevens zijn niet live per seconde; Klusio ververst ze periodiek, normaal dagelijks.

Fouten begrijpen

Elke fout bevat success: false, een leesbare error, een vaste error_code en een request_id. Geef dat request-ID door aan support; technische serverdetails blijven veilig in de log.

{
  "success": false,
  "error": "Een geldige API-key is verplicht. Gebruik de X-API-Key-header.",
  "error_code": "invalid_api_key",
  "request_id": "a1b2c3d4e5f60708"
}

Limieten en caching

Nieuwe keys starten standaard op 100 requests per uur. In API-beheer kun je per key een limiet van 1 tot 1.000 instellen. Na geldige authenticatie zie je het verbruik in deze responseheaders:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 96
X-RateLimit-Reset: 1786525200

• Cache een artikellijst 5 tot 15 minuten.
• Cache een volledig artikel tot maximaal één uur.
• Vraag Google Reviews niet vaker dan dagelijks opnieuw op.
• Gebruik bij HTTP 429 de header Retry-After; blijf niet direct opnieuw proberen.

Bestaande koppelingen

Het oude endpoint /api/blog.php blijft voorlopig bestaan zodat huidige websites niet onverwacht uitvallen. Nieuwe koppelingen horen altijd /api/v1/blogs te gebruiken. V1 heeft verplichte authenticatie, vaste validatie en voorspelbare foutcodes.

Kom je er niet uit?

Stuur naar support@klusio.nl: je company_id, het gebruikte endpoint, de HTTP-status, het request_id en het tijdstip. Stuur nooit je volledige API-key mee.