Public Content API

De Public Content API geeft je alleen-lezen programmatische toegang tot de blogposts in je Nolorem-organisatie. Gebruik het om content op te halen naar een Drupal-site, een aangepaste front-end, een mobiele app of elk extern systeem dat je blogdata nodig heeft.

De API is beschikbaar op elk betaald abonnement, inclusief een proefperiode. Een actief abonnement is vereist; alle toegang is alleen-lezen, en publiceren en bewerken blijven binnen Nolorem.

Een API-sleutel aanmaken

Alleen organisatiebeheerders kunnen API-sleutels aanmaken.

1. Scroll in Instellingen naar de sectie API-sleutels (alleen zichtbaar voor beheerders).
2. Klik op API-sleutel aanmaken.
3. Voer een beschrijvende naam voor de sleutel in (bijvoorbeeld "Drupal-website" of "Contentsynchronisatiescript").
4. Kies het bereik voor de sleutel (zie hieronder).
5. Kopieer de sleutel die op het scherm wordt getoond. Deze begint met nlr_live_.

De sleutel wordt slechts één keer getoond. Bewaar hem onmiddellijk in een secrets manager of omgevingsvariabele. Als je hem verliest, trek je de sleutel in en maak je een nieuwe aan.

Een sleutelbereik kiezen

Wanneer je een sleutel aanmaakt, kies je of deze één specifieke blog dekt of alle blogs in je organisatie.

Blog-gebonden sleutel (aanbevolen): de sleutel is gebonden aan één enkele blog. Hij heeft alleen toegang tot posts, categorieën en tags van die blog. Als de sleutel ooit lekt of wordt gedeeld, is alleen de content van die ene blog blootgesteld.

Organisatiebrede sleutel: de sleutel heeft toegang tot alle blogs in je organisatie. Gebruik dit alleen wanneer je een bewuste reden hebt om meerdere blogs met één sleutel te benaderen.

De bereikbadge op elke sleutel in de lijst toont aan welke blog de sleutel gebonden is, of "Alle blogs" voor een organisatiebrede sleutel. Het bereik ligt vast bij aanmaak. Om het bereik te wijzigen, maak je een nieuwe sleutel aan met het gewenste bereik, werk je alle consumenten bij en trek je vervolgens de oude sleutel in.

Verzoeken authenticeren

Geef de sleutel mee in de Authorization-header van elk verzoek:

Authorization: Bearer nlr_live_your_key_here

Voorbeeld met curl:

curl https://nolorem.io/api/v1/posts \
  -H "Authorization: Bearer nlr_live_your_key_here"

De API is server-naar-server. Er zijn geen CORS-headers, dus browserclients kunnen hem niet rechtstreeks aanroepen. Doe alle API-aanroepen vanuit je back-end of een server-side script.

Je blogs oplijsten

GET /api/v1/blogs lijst de blogs op waartoe je sleutel toegang heeft. De vorm van het antwoord is hetzelfde of de sleutel nu blog-gebonden of organisatiebreed is.

curl https://nolorem.io/api/v1/blogs \
  -H "Authorization: Bearer nlr_live_your_key_here"

Antwoord:

{
  "data": [
    { "id": "uuid", "slug": "my-blog", "name": "My Blog" },
    { "id": "uuid", "slug": "company-news", "name": "Company News" }
  ]
}

Een blog-gebonden sleutel geeft precies één item terug (de gebonden blog). Een organisatiebrede sleutel geeft alle blogs terug. Gebruik dit endpoint om te ontdekken welke blogs een sleutel dekt voordat je content ophaalt.

Posts filteren op blog

Alle content-endpoints accepteren een optionele blog-parameter. Geef ofwel de blog-UUID ofwel de slug mee:

# Filter by slug
curl "https://nolorem.io/api/v1/posts?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Filter by UUID
curl "https://nolorem.io/api/v1/posts?blog=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Als je blog weglaat, geeft de API content terug van alle blogs waartoe je sleutel toegang heeft (het standaard, niet-brekende gedrag).

Als je een blog-gebonden sleutel gebruikt en ?blog= meegeeft die naar een andere blog wijst, geeft de API 403 Forbidden terug. Dit voorkomt dat men raadt welke blogs er in een organisatie bestaan.

Dezelfde blog-parameter werkt op /api/v1/categories en /api/v1/tags.

Posts oplijsten

GET /api/v1/posts geeft een gepagineerde lijst met posts terug voor de blogs waartoe je sleutel toegang heeft. Standaard geeft het gepubliceerde posts terug, 20 per pagina.

curl "https://nolorem.io/api/v1/posts?status=published&per_page=50" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Antwoord:

{
  "data": [
    {
      "id": "uuid",
      "blog_id": "uuid",
      "title": "My blog post",
      "slug": "my-blog-post",
      "excerpt": "Lead paragraph...",
      "language": "en",
      "available_locales": ["en", "nl"],
      "locale_slugs": {
        "en": "my-blog-post",
        "nl": "mijn-blogbericht-over-contentgeneratie"
      },
      "category": "Technology",
      "tags": ["AI", "Productivity"],
      "featured_image_url": "https://...",
      "published_at": "2026-06-01T10:00:00Z",
      "updated_at": "2026-06-10T14:30:00Z",
      "html": null
    }
  ],
  "meta": { "page": 1, "per_page": 50, "total": 123 }
}

Het veld html is altijd null in lijstantwoorden. Gebruik de detail-endpoints om de volledige posttekst te krijgen.

Beschikbare filters

Parameter	Beschrijving	Voorbeeld
blog	Blog-UUID of slug (standaard: alle toegankelijke blogs)	blog=my-blog
status	published, draft of scheduled (standaard: published)	status=published
language	ISO 639-1 taalcode	language=nl
category	Categorienaam (niet-hoofdlettergevoelig)	category=Technology
tag	Tagnaam (niet-hoofdlettergevoelig)	tag=AI
updated_since	ISO 8601 datum-tijd; alleen posts gewijzigd na deze datum	updated_since=2026-06-01T00:00:00Z
page	Paginanummer, beginnend bij 1	page=2
per_page	Items per pagina, max 100	per_page=100

Een post in een andere taal ophalen

language en locale lijken op elkaar en doen het tegenovergestelde. Lees dit een keer en je haalt ze niet meer door elkaar.

language filtert. Hij bepaalt welke posts je terugkrijgt, op de taal waarin een post geschreven is. ?language=nl geeft je Nederlandse posts terug en laat de Engelse weg.

locale filtert niets. Hij geeft de posts terug die je toch al kreeg, maar in de gevraagde taal, telkens als daarvan een volledige vertaling bestaat. ?locale=nl op de lijst-endpoint geeft nog steeds elke post terug: die met een volledige Nederlandse vertaling komen terug met hun Nederlandse title, slug, excerpt, seo_title en seo_description, de rest komt onveranderd terug.

Gebruik je vandaag ?language=? Voor jou verandert er niets. Laat locale weg en elk veld dat je al las houdt precies de waarde die het had, en language houdt de betekenis die het altijd had. Het enige verschil zijn de twee velden hieronder, die voortaan in elk antwoord aanwezig zijn.

# Elke post, in het Nederlands waar een volledige Nederlandse vertaling bestaat
curl "https://nolorem.io/api/v1/posts?locale=nl" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Een post, in het Nederlands, inclusief de HTML-tekst en de alt-teksten van de beelden
curl "https://nolorem.io/api/v1/posts/550e8400-e29b-41d4-a716-446655440000?locale=nl" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Op de twee detail-endpoints omvat de projectie ook html en de alt-tekst van elk item in images, zodat de hele pagina in één taal staat.

Een vertaling die nog niet af is, telt niet mee. Is de vertaling voor de gevraagde taal niet afgerond, dan krijg je de bronversie onveranderd terug, nooit een pagina die halverwege van taal wisselt. language blijft in elk antwoord de brontaal noemen, of je nu locale meegeeft of niet.

De slug-endpoint accepteert ook een vertaalde slug. Met locale erbij matcht /api/v1/posts/slug/{slug} ook de slug die die taal draagt, niet alleen de bron-slug: /api/v1/posts/slug/contentkalender-vullen-met-geautomatiseerde-contentgeneratie?locale=nl geeft dezelfde post terug als zijn Engelse adres. De bron-slug wordt eerst geprobeerd en wint altijd, zodat een vertaalde slug nooit het eigen adres van een andere post kan overdekken. Laat je locale weg, dan matcht alleen de bron-slug en geeft een vertaalde slug op zichzelf 404.

Weten welke talen een post heeft

Je hoeft niet te gokken en je hoeft geen aanvraag per taal te doen. Elke post draagt twee velden, in lijstantwoorden net zo goed als in detailantwoorden:

{
  "language": "en",
  "available_locales": ["en", "nl"],
  "locale_slugs": {
    "en": "why-automated-content-generation-fixes-your-empty-calendar",
    "nl": "contentkalender-vullen-met-geautomatiseerde-contentgeneratie"
  }
}

available_locales somt elke taal op waarin deze post geserveerd kan worden, altijd inclusief zijn brontaal. Een taal staat er alleen in wanneer ?locale= er echt een volledige pagina in kan leveren, dus je kunt de lijst veilig gebruiken om je hreflang-tags mee op te bouwen.

locale_slugs geeft de slug die elk van die talen draagt. Merk op dat de twee slugs hierboven meer verschillen dan één vertaald woord: elke taal kiest zijn eigen slug rond zijn eigen doelzoekwoord, dus je kunt de ene niet uit de andere afleiden. Gebruik deze kaart om per taal de URL op je eigen site te bouwen.

Een enkele post ophalen

Haal een post op via zijn UUID om de volledige HTML-tekst te krijgen:

curl "https://nolorem.io/api/v1/posts/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Of via de slug:

curl "https://nolorem.io/api/v1/posts/slug/my-blog-post" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Beide geven een enkel PublicPost-object terug (niet ingepakt in een data-array) met het html-veld ingevuld.

Beide endpoints gebruiken standaard status=published, net als het lijst-endpoint hierboven. Een post opvragen via id of slug die niet gepubliceerd is, geeft nu 404 terug, tenzij je ?status=draft of ?status=scheduled aan het verzoek toevoegt.

Incrementele synchronisatie met updated_since

Om alleen nieuwe of gewijzigde content te synchroniseren, sla je de tijdstempel van je laatste succesvolle synchronisatie op en geef je die mee als updated_since bij de volgende run:

# Initial sync: fetch all published posts
curl "https://nolorem.io/api/v1/posts?per_page=100" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# Subsequent syncs: only posts changed since last sync
curl "https://nolorem.io/api/v1/posts?updated_since=2026-06-10T14:30:00Z&per_page=100" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Doorloop alle resultaten met paginering voordat je je nieuwe synchronisatietijdstempel opslaat.

Ongepubliceerde of verwijderde posts detecteren

Wanneer je updated_since gebruikt voor incrementele synchronisatie, geeft het standaardantwoord alleen posts terug die nog gepubliceerd zijn. Als een post sinds je laatste synchronisatie in Nolorem is gedepubliceerd of verwijderd, verdwijnt hij simpelweg uit de resultaten zonder signaal om hem op de bestemming te verwijderen.

Om dat signaal te krijgen, geef je include_deleted=true mee samen met je updated_since-tijdstempel:

curl "https://nolorem.io/api/v1/posts?updated_since=2026-06-10T14:30:00Z&include_deleted=true" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Het antwoord bevat alle live posts zoals gewoonlijk, plus minimale tombstone-items die aan het einde van data worden toegevoegd. Elke tombstone heeft:

• id: de post-UUID die je al hebt van een eerdere synchronisatie
• status: de huidige status van de post, of "deleted" als hij permanent is verwijderd
• updated_at: wanneer de wijziging plaatsvond
• deleted: true als de post is verwijderd, false als hij simpelweg is gedepubliceerd of naar concept is verplaatst

{
  "data": [
    { "id": "...", "title": "Live post", "updated_at": "..." },
    { "id": "...", "status": "draft", "updated_at": "...", "deleted": false },
    { "id": "...", "status": "deleted", "updated_at": "...", "deleted": true }
  ],
  "meta": { "page": 1, "per_page": 20, "total": 1, "tombstones": 2 }
}

Gebruik meta.tombstones om te weten hoeveel tombstone-items worden toegevoegd. meta.total weerspiegelt altijd alleen live posts.

Wanneer je synchronisatietool een tombstone ziet, depubliceer of verwijder je de bijbehorende pagina op de bestemming (stel bijvoorbeeld de bijbehorende Drupal-node in op gedepubliceerd of concept).

Zonder include_deleted=true is het gedrag identiek aan voor deze wijziging: alleen live gepubliceerde posts worden teruggegeven.

Categorieën en tags oplijsten

Twee endpoints geven de volledige categorie- en tagtaxonomie van je blog terug. Deze zijn nuttig voor externe tools die Nolorem-categorieën of -tags aan hun eigen taxonomie moeten koppelen (bijvoorbeeld een Drupal-connector die Nolorem-categorieën koppelt aan Drupal-vocabulairetermen). Beide accepteren de blog-parameter.

# All categories for your organisation (or the scoped blog)
curl "https://nolorem.io/api/v1/categories?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

# All tags for your organisation (or the scoped blog)
curl "https://nolorem.io/api/v1/tags?blog=my-blog" \
  -H "Authorization: Bearer nlr_live_your_key_here"

Beide geven de volledige lijst in één antwoord terug (niet gepagineerd):

{ "data": [{ "id": "uuid", "name": "Marketing" }, { "id": "uuid", "name": "Technology" }] }

Dezelfde bearer-token, vereiste van een actief abonnement en posts:read-bereik gelden als voor de posts-endpoints.

Gebruiksanalyse per sleutel

In Instellingen kan elke sleutelrij worden uitgevouwen om gebruiksanalyse te tonen:

• Verzoeken (laatste 24u / totaal): hoeveel API-aanroepen deze sleutel heeft gedaan.
• Aparte bronnen: hoeveel aparte IP-adressen en clientapplicaties deze sleutel recent hebben gebruikt.
• Laatst gebruikt: de tijdstempel van het meest recente geauthenticeerde verzoek.

Deze analyses helpen je begrijpen hoe je sleutels worden gebruikt en onverwachte patronen op te sporen.

Vlag voor gedeelde sleutel

Als een sleutel een groot aantal aparte IP-adressen in een korte periode toont, kan Nolorem hem markeren als "mogelijk gedeeld of gecompromitteerd". De vlag verschijnt als een amberkleurige waarschuwing op de sleutelrij. De sleutel blijft werken en er wordt geen automatische actie ondernomen; dit is een adviserend signaal.

Wanneer je de vlag ziet, bekijk je je gebruikslogboeken. Als je de sleutel opzettelijk hebt gedeeld (bijvoorbeeld met meerdere servers in een cluster), overweeg dan of het toegangspatroon verwacht is. Als de sleutel mogelijk is gelekt of gedeeld met onbedoelde partijen, trek hem dan in en maak een nieuwe aan om de toegang te beperken.

Snelheidslimieten

Elke API-sleutel is onderworpen aan deze limieten:

• 60 verzoeken per minuut
• 5.000 verzoeken per dag

Wanneer je een limiet overschrijdt, geeft de API HTTP 429 terug met een Retry-After-header die aangeeft hoeveel seconden je moet wachten voor je opnieuw probeert:

HTTP/1.1 429 Too Many Requests
Retry-After: 43

{ "error": "Rate limit exceeded" }

Implementeer exponentiële backoff voor betrouwbare, langlopende synchronisatiescripts.

Foutcodes

Status	Betekenis
400	Ongeldige queryparameters
401	Ontbrekende of ongeldige API-sleutel
403	Actief abonnement vereist, sleutel mist posts:read-bereik, of blog-gebonden sleutel gebruikt met een niet-overeenkomende ?blog=-waarde
404	Post niet gevonden
429	Snelheidslimiet overschreden (controleer de Retry-After-header)

Machineleesbare specificatie

De volledige API-specificatie in OpenAPI 3.1-formaat is beschikbaar op:

GET /api/v1/openapi.json

Dit endpoint is niet-geauthenticeerd. Je kunt het importeren in Postman, Insomnia of elke OpenAPI-compatibele tool.

Een sleutel intrekken

Om een sleutel in te trekken, scroll je naar de sectie API-sleutels in Instellingen, zoek je de sleutel op naam en klik je op Intrekken. De sleutel stopt onmiddellijk met werken. Verzoeken die al onderweg en geauthenticeerd waren, worden voltooid, maar geen enkel nieuw verzoek met de ingetrokken sleutel zal slagen.