Öffentliche API

Die Öffentliche API gibt Administratoren deiner Organisation direkten HTTP-Zugriff auf die Live-Daten deiner Organisation — binde sie in jede Website, App, jeden Bot oder jede Automatisierung ein, die eine HTTP-Anfrage stellen kann. Sie ist eine Funktion des Business-Plans.

Der Schlüssel ist auf deine Organisation beschränkt — alle Endpunkte arbeiten automatisch auf dieser Gruppe. Basis-URL: https://api.ludoya.com/public/v1. Auth-Header: X-Api-Key: YOUR_KEY. Rate Limit: 100 Anfragen pro Minute, danach erhältst du einen 429.

Schlüssel beginnen mit ldy_ und sind 36 Zeichen lang, sodass sie in einer Konfigurationsdatei leicht zu erkennen sind — und leicht zu scannen, falls einer einmal dort landet, wo er nicht hingehört. Behandle ihn wie ein Passwort: nur serverseitig verwenden und auf derselben Seite widerrufen, falls er in falsche Hände gerät.

Worauf du zugreifen kannst

• Orte — die in deiner Gruppe verfügbaren Orte und deren Plätze; werden als Eingabe beim Erstellen von Veranstaltungen verwendet
• Veranstaltungen (Lesen) — bevorstehende und vergangene Veranstaltungen mit Titel, Beschreibung, Datum/Uhrzeit, Zeitzone, Kapazität, Anzahl der Teilnehmenden und Status
• Veranstaltungen (Schreiben) — erstelle und aktualisiere Veranstaltungen per POST und PUT, mit voller Kontrolle über Ort, Kapazität, Berechtigungen, Sichtbarkeit und Bild
• Unterveranstaltungen — liste die innerhalb einer übergeordneten Veranstaltung verschachtelten Veranstaltungen auf
• Teilnehmende — füge jemanden zu einer Veranstaltung hinzu, ändere deren Teilnahme oder entferne sie
• Mitglieder — Mitgliederliste mit Benutzerprofilen und Rollen (Eigentümer, Admin, Mitglied), paginiert
• Einladungen — lade jemanden in deine Gruppe ein
• Suche — suche nach Ludoya-Benutzern und im Brettspielkatalog, damit du Namen vor dem Schreiben in IDs auflösen kannst
• Sammlung — Spielesammlung mit Filterung nach Besitz, Name, Spielerzahl und Liste; sortierbar und paginiert; jedes Spiel enthält BGG-Metadaten
• Statistiken — Partiestatistiken für beliebige Zeiträume: Summen, Durchschnitte, Top-Spieler mit Siegen und Punktzahlen, Aufschlüsselung nach Spielerzahl, pro Ort und pro Spiel
• Kampagnen (Lesen) — liste die Kampagnen der Gruppe mit Mitglieder- und Sitzungszahlen; rufe vollständige Kampagnendetails ab, einschließlich Mitglieder, vergangene Sitzungen und geplante Veranstaltungen
• Kampagnen (Schreiben) — erstelle Kampagnen für die Gruppe und aktualisiere ihren Namen, ihre Beschreibung, ihren Status und ihre Sichtbarkeit
• Kampagnenmitglieder — füge Personen zu einer Kampagne hinzu, aktualisiere sie und entferne sie

Endpunkte

GET /locations

Gibt die in der Gruppe verfügbaren Orte zurück. Jeder Ort hat die Felder id, name, optional address, capacity, das Flag isDefault und das Array spots (jeder Platz mit eigener id, name und capacity). Verwende Orts- und Platz-IDs beim Erstellen von Veranstaltungen.

Mit Ludoya anmelden

Die gleiche Seite, auf der sich dein API-Schlüssel befindet, macht deine Organisation auch zu einem Anmeldeanbieter. Lass Leute sich auf deiner eigenen Website, in deinem Forum oder auf deiner Community-Plattform mit ihrem Ludoya-Konto anmelden — kein separates Passwort, das sie vergessen könnten, und keine Benutzerdatenbank, die du betreiben musst.

Warum es sich lohnt

Wenn jemand die Anmeldung genehmigt, wird die Person mit deiner Organisation verknüpft: abhängig von der Beitrittsrichtlinie deiner Gruppe werden sie sofort Mitglied (offen), stellen eine Beitrittsanfrage, die ein Admin genehmigen muss (Beitrittsanfrage), oder melden sich einfach an, ohne beizutreten (nur auf Einladung). In jedem Fall erscheinen sie im Endpoint /members wie alle anderen — so bleiben der Login deiner Website und deine Ludoya-Mitgliederliste automatisch synchron.

So richtest du es ein

Es ist Standard‑OpenID Connect, daher benötigen die meisten Plattformen nichts weiter als eine Issuer‑URL plus eine Client‑ID und ein Secret. Registriere deine Anwendung auf der Public‑API‑Seite, um diese Zugangsdaten zu erhalten, und liste die Redirect‑URIs auf, die deine Website verwenden wird — du kannst mehrere registrieren, und jede muss dem redirect_uri, den deine Website sendet, zeichengetreu entsprechen, einschließlich des abschließenden Schrägstrichs. Eine kleine Abweichung ist der häufigste Grund, warum ein erster Anmeldeversuch scheitert.

• Discourse — installiere das OpenID‑Connect‑Plugin, füge die Discovery‑URL ein, füge die Anmeldedaten hinzu
• WordPress — jedes generische OpenID‑Connect‑Plugin, mit der Option "auto discover"
• Alles andere — wenn es OIDC spricht, gib die Issuer‑URL an und es konfiguriert sich selbst

Jede Anmeldung liefert die permanente Kennung der Person, ihren Benutzernamen, Anzeigenamen und Avatar sowie ihre E‑Mail‑Adresse. Vollständige Einrichtungsanweisungen, einschließlich des manuellen Flows, findest du im In‑App‑Entwicklerhandbuch unter Entwickler → Mit Ludoya anmelden.

Für alle, die sich anmelden

Jede Person, die Ludoya zur Anmeldung irgendwo genutzt hat, kann diese Verbindungen unter Einstellungen → Verbundene Apps einsehen, sehen, wann jede verbunden und zuletzt verwendet wurde, und jede davon jederzeit trennen. Das Trennen beendet den Zugriff der Website sofort, entfernt sie jedoch nicht aus deiner Gruppe.

GET /events

Gibt zukünftige und vergangene Veranstaltungen in separaten, paginierten Listen zurück.

Jede Veranstaltung enthält: type (MEETUP oder PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (Benutzerobjekt oder null), master (Benutzerobjekt oder null). Benutzerobjekte enthalten id, username, name, avatarUrl.

POST /events

Erstellt eine Veranstaltung in der Gruppe. Erforderliche Felder: type und title. Wenn locationId weggelassen wird, wird der Standardort der Gruppe verwendet; falls keiner vorhanden ist, wird 400 zurückgegeben.

Optionale Felder umfassen: description, locationId, spotId, gameId, parentEventId (für Unterveranstaltungen), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Das Feld image akzeptiert {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Max. 5 MB.

Gibt {"id": "string"} mit Status 201 zurück.

PUT /events/{eventId}

Aktualisiert eine bestehende Veranstaltung. Gleiche Body-Struktur wie bei POST — gib nur die Felder an, die du ändern möchtest. Der Aufrufer muss der Organisator der Veranstaltung (das Gruppenkonto) sein. Gibt 202 mit leerem Body zurück.

GET /events/{eventId}

Ruft eine einzelne Veranstaltung anhand der ID ab, mit derselben Struktur wie die Einträge in GET /events.

GET /events/{eventId}/children

Listet die in einer übergeordneten Veranstaltung verschachtelten Unterveranstaltungen auf — die einzelnen Themenstränge oder Sitzungen einer größeren Veranstaltung. Jede Unterveranstaltung hat dieselbe Struktur wie eine normale Veranstaltung.

Teilnehmende verwalten

Drei Endpunkte ermöglichen es dir, die Teilnehmerliste einer Veranstaltung außerhalb von Ludoya zu verwalten — praktisch, wenn Anmeldungen auf deiner eigenen Website stattfinden oder wenn du eine bestehende Liste importierst.

GET /members

Gibt eine paginierte Mitgliederliste zurück.

Jedes Mitglied umfasst: id, username, name, avatarUrl, role (OWNER, ADMIN oder MEMBER).

POST /members/invite

Lädt jemanden in deine Gruppe ein. Dieser Aufruf akzeptiert einen username direkt — keine ID-Suche nötig —, sodass du Mitglieder direkt von deiner eigenen Website oder deinem Admin-Tool hinzufügen kannst.

GET /search/users und GET /search/boardgames

Die beiden Such-Endpunkte. Die meisten Schreiboperationen benötigen eine ID statt eines Namens, und über diese bekommst du eine.

GET /search/users

GET /search/boardgames

Der Brettspielfilter verwendet dieselbe durch Semikolons getrennte Form key=value wie der Sammlungsfilter, sodass du den Katalog nach Spielerzahl, Spielzeit, Komplexität, Jahr, Alter oder Tags durchsuchen kannst.

GET /collection

Gibt deine Spielesammlung mit Filterung, Sortierung und Paginierung zurück.

Antwort: totalGames, totalExpansions, games[] — jeweils mit: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Gibt Partie-Statistiken für ein konfigurierbares Zeitfenster zurück.

Die Antwort enthält:

• Zusammenfassung — Partien insgesamt, gesamte/durchschnittliche Spielzeit, Anzahl eindeutiger Spiele, Spieler und Orte
• Nach Spieler — Partien pro Person, Siege, durchschnittliche und beste Punktzahl
• Nach Spielerzahl — Aufschlüsselung der 2‑Spieler‑, 3‑Spieler‑, 4‑Spieler‑Spiele usw.
• Nach Ort — Anzahl der Partien und eindeutige Spiele pro Ort
• Nach Spiel — Anzahl der Partien, gesamte/durchschnittliche Spielzeit und eindeutige Spieler pro Titel

GET /campaigns

Gibt eine paginierte Liste von Kampagnen zurück, die zur Gruppe gehören.

Jede Kampagne enthält: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Gibt die vollständigen Details einer Kampagne zurück, die zur Gruppe gehört.

Die Antwort umfasst: Alle Felder der Liste, plus template, description, globalNotes, globalState, members[] (jeweils mit user, role, characterNotes, characterState), sessions[] und events[].

POST /campaigns

Erstellt eine Kampagne für die Gruppe. Pflichtfelder: gameId und name. Die Sichtbarkeit ist standardmäßig nur für Gruppenmitglieder (ONLY_GROUP), wenn sie weggelassen wird.

Optionale Felder: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS oder PRIVATE).

Gibt {"id": "string"} mit Status 201 zurück.

PUT /campaigns/{campaignId}

Aktualisiert eine bestehende Kampagne. Alle Felder sind optional — gib nur an, was du ändern möchtest.

Optionale Felder: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Gibt 202 mit leerem Body zurück.

Mitglieder der Kampagne

Verwalte, wer in einer Kampagne ist, genauso wie du die Teilnehmenden einer Veranstaltung verwaltest.

Fehlercodes

Erste Schritte

1. Einen API-Schlüssel generieren

1. Geh zur Profilseite deiner Organisation
2. Tippe auf das Menü (⋮) → Öffentliche API
3. Tippe auf Schlüssel generieren
4. Kopiere deinen Schlüssel sofort — er wird nur einmal angezeigt und lässt sich später nicht mehr abrufen

Der Schlüssel gehört zu deiner Organisation. Halte ihn geheim: Wer ihn hat, kann alle oben genannten Daten lesen und schreiben.

2. Widerrufen oder neu generieren

Um einen bestehenden Schlüssel zu widerrufen, geh zurück auf die Seite Öffentliche API und tippe auf Widerrufen. Bestätige den Dialog. Jedes System, das den alten Schlüssel verwendet, erhält sofort 401-Fehler. Um einen neuen Schlüssel auszustellen, tippe erneut auf Schlüssel generieren.

Siehe auch:

• Organisationen — Organisationskonten und Premium‑Funktionen
• Premium — Preise des Business‑Plans
• Integrationen — weitere Möglichkeiten, Ludoya mit externen Tools zu verbinden