Publieke API

De Openbare API geeft beheerders van de organisatie directe HTTP-toegang tot de livegegevens van je organisatie — haal ze binnen in elke website, app, bot of automatisering die een HTTP-verzoek kan doen. Het is een functie van het Business-abonnement.

De sleutel is beperkt tot je organisatie — alle eindpunten werken automatisch op die groep. Basis-URL: https://api.ludoya.com/public/v1. Auth-header: X-Api-Key: YOUR_KEY. Snelheidslimiet: 100 aanvragen per minuut, waarna je een 429 krijgt.

Sleutels beginnen met ldy_ en zijn 36 tekens lang, waardoor ze gemakkelijk te herkennen zijn in een configuratiebestand — en eenvoudig te scannen als er ooit een terechtkomt waar hij niet hoort. Behandel hem als een wachtwoord: alleen aan de serverzijde gebruiken, en trek hem op dezelfde pagina in als hij uitlekt.

Waar je toegang toe hebt

• Locaties — de beschikbare locaties van je groep en hun plekken; gebruikt als invoer bij het aanmaken van evenementen
• Evenementen (lezen) — aankomende en afgelopen evenementen met titel, beschrijving, datum/tijd, tijdzone, capaciteit, aantal deelnemers en status
• Evenementen (schrijven) — maak en werk evenementen bij via POST en PUT, met volledige controle over locatie, capaciteit, machtigingen, zichtbaarheid en afbeelding
• Subevenementen — lijst de evenementen op die genest zijn binnen een hoofdevenement
• Deelnemers — voeg iemand toe aan een evenement, wijzig hun aanwezigheid of verwijder ze
• Leden — ledenlijst met gebruikersprofielen en rollen (Eigenaar, Beheerder, Lid), gepagineerd
• Uitnodigingen — nodig iemand uit in je groep
• Zoeken — zoek Ludoya-gebruikers en in de bordspelcatalogus, zodat je namen naar ID’s kunt omzetten voordat je wegschrijft
• Collectie — spelcollectie met filtering op eigendom, naam, aantal spelers en lijst; sorteerbaar en gepagineerd; elk spel bevat BGG-metagegevens
• Statistieken — speelstatistieken voor elke periode: totalen, gemiddelden, topspelers met overwinningen en scores, uitsplitsingen per spelersaantal, per locatie en per spel
• Campagnes (lezen) — geef de campagnes van de groep weer met leden- en sessieaantallen; haal volledige campagnedetails op, inclusief leden, eerdere sessies en geplande evenementen
• Campagnes (schrijven) — maak campagnes voor de groep en werk hun naam, beschrijving, status en zichtbaarheid bij
• Campagneleden — voeg personen toe aan een campagne, werk ze bij en verwijder ze

Eindpunten

GET /locations

Geeft de beschikbare locaties van de groep terug. Elke locatie heeft een id, name, optioneel address, capacity, een isDefault-vlag en een spots-array (elke plek heeft een eigen id, name en capacity). Gebruik locatie- en plek-ID’s bij het aanmaken van evenementen.

Inloggen met Ludoya

Dezelfde pagina die je API-sleutel bevat, maakt je organisatie ook tot een aanmeldprovider. Laat mensen met hun Ludoya-account inloggen op je eigen website, forum of communityplatform — geen apart wachtwoord dat ze kunnen vergeten, en geen gebruikersdatabase die jij hoeft te beheren.

Waarom het de moeite waard is

Wanneer iemand het inloggen goedkeurt, wordt diegene gekoppeld aan je organisatie: afhankelijk van het toelatingsbeleid van je groep worden ze meteen lid (open), dienen ze een verzoek in om lid te worden voor een beheerder om goed te keuren (verzoek om lid te worden), of loggen ze eenvoudigweg in zonder lid te worden (alleen op uitnodiging). Hoe dan ook verschijnen ze in het /members-endpoint zoals iedereen — zo blijven het inloggen op je website en je Ludoya-ledenlijst automatisch gesynchroniseerd.

Instellen

Het is standaard OpenID Connect, dus de meeste platforms hebben niets meer nodig dan een issuer-URL plus een client-ID en secret. Registreer je applicatie via de Public API-pagina om die inloggegevens te krijgen, en geef de redirect-URI's op die je site zal gebruiken — je kunt er meerdere registreren, en elke moet exact overeenkomen met de redirect_uri die je site verstuurt teken voor teken, inclusief de afsluitende slash. Een bijna-treffer is de meest voorkomende reden dat een eerste inlogpoging mislukt.

• Discourse — installeer de OpenID Connect-plug-in, plak de discovery-URL en voeg de inloggegevens toe
• WordPress — elke generieke OpenID Connect-plug-in, met de optie "auto discover"
• Al het overige — als het OIDC spreekt, wijs het naar de issuer-URL en het configureert zichzelf

Elke aanmelding retourneert de permanente identifier van de persoon, hun gebruikersnaam, weergavenaam en avatar, en hun e‑mailadres. Volledige installatie-instructies, inclusief de handmatige flow, staan in de ontwikkelaarsgids in de app onder Ontwikkelaars → Inloggen met Ludoya.

Voor de mensen die inloggen

Iedereen die Ludoya heeft gebruikt om ergens in te loggen, kan die verbindingen bekijken onder Instellingen → Verbonden apps, zien wanneer elke verbinding tot stand is gebracht en voor het laatst is gebruikt, en er op elk moment een verbreken. Het verbreken beëindigt de toegang van de site onmiddellijk, maar verwijdert ze niet uit je groep.

GET /events

Retourneert toekomstige en afgelopen evenementen in afzonderlijke, gepagineerde lijsten.

Elk evenement bevat: type (MEETUP of PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (gebruikersobject of null), master (gebruikersobject of null). Gebruikersobjecten bevatten id, username, name, avatarUrl.

POST /events

Maakt een evenement aan in de groep. Verplichte velden: type en title. Als locationId wordt weggelaten, wordt de standaardlocatie van de groep gebruikt; als die niet bestaat, wordt 400 geretourneerd.

Optionele velden zijn onder meer: description, locationId, spotId, gameId, parentEventId (voor subevenementen), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Het veld image accepteert {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Max. 5 MB.

Retourneert {"id": "string"} met status 201.

PUT /events/{eventId}

Werkt een bestaand evenement bij. Zelfde requestbody-structuur als bij POST — neem alleen de velden op die je wilt wijzigen. De aanvrager moet de organisator van het evenement (de groepsaccount) zijn. Retourneert 202 met lege body.

GET /events/{eventId}

Haalt één enkel evenement op op basis van ID, met dezelfde structuur als de items in GET /events.

GET /events/{eventId}/children

Geeft de subevenementen weer die genest zijn binnen een hoofdevenement — de afzonderlijke tracks of sessies van een grotere bijeenkomst. Elk subevenement heeft dezelfde structuur als een gewoon evenement.

Deelnemers beheren

Met drie eindpunten kun je de deelnemerslijst van een evenement buiten Ludoya beheren — handig als aanmeldingen via je eigen website verlopen, of als je een bestaande lijst importeert.

GET /members

Geeft een gepagineerde ledenlijst terug.

Elk lid bevat: id, username, name, avatarUrl, role (OWNER, ADMIN, of MEMBER).

POST /members/invite

Nodigt iemand uit voor je groep. Deze accepteert een username direct — je hoeft geen ID op te zoeken — zodat je leden rechtstreeks vanaf je eigen site of beheertool kunt toevoegen.

GET /search/users en GET /search/boardgames

De twee opzoek-endpoints. De meeste schrijfhandelingen hebben een id nodig in plaats van een naam, en hiermee kun je er een ophalen.

GET /search/users

GET /search/boardgames

Het bordspellenfilter gebruikt dezelfde door puntkomma's gescheiden key=value-vorm als het collectiefilter, zodat je de catalogus kunt doorzoeken op aantal spelers, speelduur, complexiteit, jaar, leeftijd of tags.

GET /collection

Retourneert je spelcollectie met filtering, sortering en paginering.

Antwoord: totalGames, totalExpansions, games[] — elk met: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Retourneert statistieken van speelsessies voor een configureerbaar tijdvenster.

De respons bevat:

• Samenvatting — totaal aantal speelsessies, totale/gemiddelde speeltijd, aantallen unieke spellen, spelers en locaties
• Per speler — speelsessies per persoon, overwinningen, gemiddelde en beste score
• Per aantal spelers — uitsplitsing van spellen voor 2, 3, 4 spelers, enz.
• Per locatie — aantal speelsessies en unieke spellen per locatie
• Per spel — aantal speelsessies, totale/gemiddelde speeltijd en unieke spelers per titel

GET /campaigns

Geeft een gepagineerde lijst met campagnes die bij de groep horen.

Elke campagne bevat: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Retourneert de volledige details van een campagne die bij de groep hoort.

Het antwoord bevat: Alle lijstvelden, plus template, description, globalNotes, globalState, members[] (elk met user, role, characterNotes, characterState), sessions[] en events[].

POST /campaigns

Maakt een campagne voor de groep. Vereiste velden: gameId en name. De zichtbaarheid is standaard alleen voor groepsleden (ONLY_GROUP) indien weggelaten.

Optionele velden: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS of PRIVATE).

Retourneert {"id": "string"} met status 201.

PUT /campaigns/{campaignId}

Werkt een bestaande campagne bij. Alle velden zijn optioneel — neem alleen op wat je wilt wijzigen.

Optionele velden: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Retourneert 202 met een lege body.

Campagneleden

Beheer wie er in een campagne zit, op dezelfde manier als je deelnemers aan een evenement beheert.

Foutcodes

Aan de slag

1. Een API-sleutel genereren

1. Ga naar de profielpagina van je organisatie
2. Tik op het menu (⋮) → Openbare API
3. Tik op Sleutel genereren
4. Kopieer je sleutel meteen — hij wordt slechts één keer getoond en kan later niet meer worden opgehaald

De sleutel is gekoppeld aan je organisatie. Houd hem geheim: iedereen met de sleutel kan alle bovenstaande gegevens lezen en schrijven.

2. Intrekken of opnieuw genereren

Om een bestaande sleutel in te trekken, ga terug naar de pagina Openbare API en tik op Intrekken. Bevestig het dialoogvenster. Elk systeem dat de oude sleutel gebruikt, krijgt onmiddellijk 401-fouten. Om een nieuwe sleutel uit te geven, tik opnieuw op Sleutel genereren.

Zie ook:

• Organisaties — organisatieaccounts en premiumfuncties
• Premium — prijzen van het Business-plan
• Integraties — andere manieren om Ludoya met externe tools te verbinden