Training Metadata API

Met de Training Metadata API haal je de catalogusmetadata van SkillsTown direct op in je eigen LMS, in plaats van de CSV-bestanden die voorheen handmatig werden uitgewisseld. Voor jou als integrator is het een read-only, machine-to-machine API: twee GET-eindpunten, geen schrijfacties, geen gebruikerssessie.

Deze pagina behandelt twee onderwerpen, in deze volgorde:

1. Hoe kan ik een Admin API-sleutel aanvragen?
2. Hoe jij als integrator die key gebruikt om de eindpunten op te roepen.

1. API-key

Om dit te laten werken, heb je de API-sleutel van je organisatie nodig. Je kunt deze aanvragen via [email protected] of bij je technische contactpersoon.

2. De eindpunten oproepen

Zodra je een key hebt, moet elke aanvraag deze meesturen in de X-Api-Key-header:

X-Api-Key: <your-api-key>

De key identificeert het oproepende bedrijf — er zit geen companyId in de key zelf en geen gebruikersidentiteit in de aanvraag. Als klantintegratie hoef je dus nooit een companyId-queryparameter mee te sturen; stuur je die alsnog mee, dan wordt hij stilzwijgend genegeerd. (Een companyId-parameter is alleen relevant voor interne super-admin-oproepers van SkillsTown, die geen bedrijf aan hun token hebben en de waarde daarom expliciet moeten meegeven.)

Een key die ontbreekt, leeg is of niet gevonden wordt, faalt op autorisatie voordat de aanvraag het eindpunt bereikt.

Versionering

Routes zijn geversioneerd via het URL-pad. De huidige API-versie is 1.0, die in het pad wordt aangeduid als v1 — elke URL op deze pagina heeft dus deze vorm:

/admin/v1/BundleCatalog

GET /admin/v1/BundleCatalog

Geeft alle bundels die voor jouw bedrijf zichtbaar zijn, inclusief de globale bundels van SkillsTown. De resultaten zijn gesorteerd op bundleId aflopend, dus de nieuwste bundels staan bovenaan.

Respons — 200 OK

[
  { "bundleId": 412, "bundleName": "Leadership Essentials" },
  { "bundleId": 118, "bundleName": "Compliance 2026" }
]

bundleName is een lege string als er geen naam is ingesteld, nooit null. Een bedrijf zonder zichtbare bundels krijgt 200 met een lege array [], geen 404.

Voorbeeld

curl -sS \
  -H "X-Api-Key: $SKILLSTOWN_API_KEY" \
  https://<host>/admin/v1/BundleCatalog

GET /admin/v1/BundleCatalog/{bundleId}/CourseMetadata

Geeft de metadata van elke directe cursus in de opgegeven bundel.

Padparameters

Naam	Type	Toelichting
bundleId	int	Een niet-numerieke waarde geeft 404, geen 400

Een bundel die bestaat maar van een ander bedrijf is, en een bundel-id dat helemaal niet bestaat, geven beide een identieke 404.

Respons — 200 OK

[
  {
    "courseId": 1042,
    "bundleSubscriptionTypeId": 100,
    "bundleSubscriptionName": "Premium",
    "title": "Leidinggeven aan verandering",
    "targetAudience": "Teamleiders",
    "learningObjective": "Weerstandspatronen herkennen en erop reageren",
    "courseDescription": "<p>Volledige rich-text beschrijving.</p>",
    "courseIntroduction": "<p>Korte introductieparagraaf.</p>",
    "learningTime": 45,
    "courseType": "webinar",
    "segment": "Leiderschap",
    "courseLanguage": "Nederlands",
    "courseTags": ["Leadership", "Change"],
    "ltiIdentifier": "st-course-1042",
    "publishDate": "2026-01-15T00:00:00",
    "courseImage": "https://cdn.example.com/course-1042.png"
  }
]

Voorbeeld

curl -sS \
  -H "X-Api-Key: $SKILLSTOWN_API_KEY" \
  https://<host>/admin/v1/BundleCatalog/412/CourseMetadata

Veldenoverzicht

Alle 16 velden zijn altijd aanwezig in de JSON. Velden die leeg kunnen zijn worden als null teruggegeven en niet weggelaten.

Veld	Type	Toelichting
courseId	int	SkillsTown cursus-id — stabiel, gebruik dit als correlatiesleutel
bundleSubscriptionTypeId	int	Het abonnementstype waaraan de cursus binnen de bundel hangt
bundleSubscriptionName	string	Lege string als niet ingesteld, nooit null
title	string	Uit de laatste cursusversie; lege string als niet ingesteld
targetAudience	string | null	Op cursusniveau, niet op versieniveau
learningObjective	string | null	De leerdoelen van de cursusversie
courseDescription	string | null	Bevat HTML
courseIntroduction	string | null	Bevat HTML
learningTime	int | null	Opgeslagen als geheel getal; stem de bedoelde eenheid af met SkillsTown voordat je deze weergeeft
courseType	string | null	Systeemnaam van de journey-categorie, bijv. webinar
segment	string | null	Gelokaliseerde segmentnaam — zie de regels hieronder
courseLanguage	string | null	Weergavenaam van de cursustaal, bijv. Nederlands
courseTags	string[]	Lege array als de cursus geen tags heeft; lege tagwaarden worden gefilterd
ltiIdentifier	string | null	De identifier om tegen je LMS te matchen
publishDate	date-time | null
courseImage	string | null	Absolute afbeeldings-URL

HTML-inhoud

courseDescription en courseIntroduction bevatten HTML. Saneer of render deze waarden dus als HTML en ga niet uit van platte tekst.

Velden die uit de versie komen (title, learningObjective, courseDescription, courseIntroduction, learningTime, courseType, segment en publishDate) worden allemaal uit de laatste cursusversie gelezen. Oudere versies worden niet ontsloten.

Hoe segment bepaald wordt. segment is een leesbare naam en niet het numerieke segment-id. De waarde wordt in deze volgorde bepaald:

1. De vertaling die overeenkomt met de taal van de cursus zelf.
2. Anders de nl-NL-vertaling.
3. Anders null.

Er wordt nooit een andere taal ingevuld, waardoor de waarde stabiel is over aanvragen heen.

Lege responses en foutmeldingen

Situatie	Status	Body
Bundel heeft cursussen	200	Array met cursusmetadata
Bundel is toegankelijk maar heeft geen directe cursussen	200	[]
Niet-numerieke bundleId	404	Niet te onderscheiden van een onbekende bundel
Bundel bestaat niet of is van een ander bedrijf	404	Identiek in beide gevallen
Ontbrekende, lege of ongeldige X-Api-Key	401 / 403	Autorisatiefout
Onverwachte serverfout	5xx	An error occurred while processing the request

Behandel 200 met [] als "deze bundel heeft momenteel geen cursussen" — een geldige situatie, geen fout, en geen reden om opnieuw te proberen.

Aanbevolen synchronisatiestroom

1. GET /admin/v1/BundleCatalog om te zien welke bundels je kunt zien.
2. Voor elke bundel die je nodig hebt: GET /admin/v1/BundleCatalog/{bundleId}/CourseMetadata.
3. Match elke teruggegeven cursus aan je LMS via ltiIdentifier, en gebruik courseId als sleutel in je eigen administratie.
4. Behandel 200 met [] als een geldige situatie en niet als fout.
5. Behandel 404 als "deze bundel is niet van jou of bestaat niet meer" en vraag hem niet opnieuw op.

Geen van beide eindpunten kent paginering: elk geeft de volledige verzameling in één respons terug. Er is ook geen wijzigingstijdstip of delta-mechanisme, dus een synchronisatie is altijd een volledige uitlezing. Kies een frequentie die past bij hoe vaak je catalogus daadwerkelijk verandert — dagelijks is meestal ruim voldoende.