Publiczne API

Publiczne API daje administratorom organizacji bezpośredni dostęp HTTP do danych Twojej organizacji na żywo — pobierz je do dowolnej strony, aplikacji, bota czy automatyzacji, która potrafi wysłać żądanie HTTP. To funkcja planu Club.

Klucz jest ograniczony do Twojej organizacji — wszystkie endpointy automatycznie działają na tej grupie. Bazowy URL: https://api.ludoya.com/public/v1. Nagłówek uwierzytelniania: X-Api-Key: TWOJ_KLUCZ. Limity zależą od planu: klucze Club pozwalają na 30 żądań na minutę i 2000 dziennie, klucze Business na 100 na minutę, bez limitu dziennego; powyżej dostaniesz 429.

Korzystasz z WordPressa? Nie musisz w ogóle dotykać API: darmowa wtyczka Ludoya wyświetla Twoje wydarzenia na Twojej stronie i pozwala je tworzyć oraz edytować z panelu WordPressa, tym samym kluczem.

Klucz zaczyna się od ldy_ i ma długość 36 znaków, więc łatwo go zauważyć w pliku konfiguracyjnym — i łatwo go wyszukać, jeśli kiedykolwiek trafi tam, gdzie nie powinien. Traktuj go jak hasło: używaj wyłącznie po stronie serwera i unieważnij go na tej samej stronie, jeśli wycieknie.

Do czego masz dostęp

• Lokalizacje — dostępne dla twojej grupy lokale oraz ich miejsca; używane jako dane wejściowe przy tworzeniu wydarzeń
• Wydarzenia (odczyt) — nadchodzące i minione wydarzenia z tytułem, opisem, datą/godziną, strefą czasową, limitem miejsc, liczbą uczestników i statusem
• Wydarzenia (zapis) — twórz i aktualizuj wydarzenia za pomocą POST i PUT, z pełną kontrolą nad lokalizacją, limitem miejsc, uprawnieniami, widocznością i obrazem
• Podwydarzenia — lista wydarzeń zagnieżdżonych w wydarzeniu nadrzędnym
• Uczestnicy — dodaj kogoś do wydarzenia, zmień jego status obecności lub usuń go
• Członkowie — lista członków z profilami użytkowników i rolami (Właściciel, Administrator, Członek), stronicowana
• Zaproszenia — zaproś kogoś do twojej grupy
• Wyszukiwanie — wyszukuj użytkowników Ludoya oraz katalog gier planszowych, aby przed zapisem móc przypisać nazwy do ID
• Kolekcja — kolekcja gier z filtrowaniem według posiadania, nazwy, liczby graczy i listy; sortowalna i stronicowana; każda gra zawiera metadane z BGG
• Statystyki — statystyki rozgrywek dla dowolnego okresu: sumy, średnie, najlepsi gracze z wygranymi i wynikami, podziały według liczby graczy, według lokalizacji i według gier
• Kampanie (odczyt) — lista kampanii grupy z liczbą członków i sesji; pobieraj pełne szczegóły kampanii, w tym członków, przeszłe sesje i zaplanowane wydarzenia
• Kampanie (zapis) — twórz kampanie dla grupy i aktualizuj ich nazwę, opis, status i widoczność
• Członkowie kampanii — dodawaj, aktualizuj i usuwaj osoby w kampanii

Endpointy

GET /locations

Zwraca dostępne lokalizacje grupy. Każda lokalizacja ma id, name, opcjonalny address, capacity, flagę isDefault oraz tablicę spots (każde miejsce ma własne id, name i capacity). Używaj ID lokalizacji i miejsc podczas tworzenia wydarzeń.

Zaloguj się za pomocą Ludoya

Ta sama strona, na której znajduje się Twój klucz API, zamienia też Twoją organizację w dostawcę logowania. Pozwól ludziom logować się do Twojej własnej witryny, forum lub platformy społecznościowej przy użyciu konta Ludoya — bez osobnego hasła, o którym mogliby zapomnieć, i bez bazy użytkowników, którą musisz prowadzić.

Dlaczego warto

Gdy ktoś zatwierdzi logowanie, zostaje powiązany z Twoją organizacją: w zależności od polityki dołączania do grupy albo od razu staje się członkiem (otwarta), składa prośbę o dołączenie do zatwierdzenia przez administratora (prośba o dołączenie), albo po prostu loguje się bez dołączania (tylko na zaproszenie). W każdym przypadku pojawi się w endpointzie /members jak każdy inny — dzięki temu logowanie na Twojej stronie i lista członków Ludoya pozostają zsynchronizowane automatycznie.

Jak to skonfigurować

To standardowy OpenID Connect, więc większość platform potrzebuje tylko adresu URL wystawcy oraz identyfikatora klienta i tajnego klucza. Zarejestruj swoją aplikację na stronie Public API, aby uzyskać te dane, i podaj URI przekierowania, z których będzie korzystać Twoja strona — możesz zarejestrować kilka, a każde musi odpowiadać redirect_uri wysyłanemu przez Twoją stronę znak w znak, z uwzględnieniem końcowego ukośnika. Drobna niezgodność to najczęstsza przyczyna niepowodzenia pierwszej próby logowania.

• Discourse — zainstaluj wtyczkę OpenID Connect, wklej URL odkrywania, dodaj poświadczenia
• WordPress — dowolna ogólna wtyczka OpenID Connect, używająca opcji "auto discover"
• Inne — jeśli obsługuje OIDC, wskaż URL wystawcy, a skonfiguruje się samo

Każde logowanie zwraca trwały identyfikator osoby, jej nazwę użytkownika, nazwę wyświetlaną i awatar oraz adres e-mail. Pełne instrukcje konfiguracji, w tym ręczny przebieg, znajdziesz w przewodniku dla deweloperów w aplikacji: Deweloperzy → Logowanie za pomocą Ludoya.

Dla osób logujących się

Każdy, kto użył Ludoya do zalogowania się gdzieś, może przejrzeć te połączenia w Ustawienia → Połączone aplikacje, zobaczyć, kiedy każde zostało połączone i kiedy ostatnio użyte, oraz w dowolnym momencie je odłączyć. Odłączenie natychmiast odcina dostęp witryny, ale nie usuwa ich z Twojej grupy.

GET /events

Zwraca przyszłe i przeszłe wydarzenia w oddzielnych paginowanych listach.

Każde wydarzenie zawiera: type (MEETUP lub PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (obiekt użytkownika lub null), master (obiekt użytkownika lub null). Obiekty użytkownika zawierają id, username, name, avatarUrl.

POST /events

Tworzy wydarzenie w grupie. Pola wymagane: type i title. Jeśli locationId zostanie pominięty, użyta zostanie domyślna lokalizacja grupy; jeśli żadna nie istnieje, zwraca 400.

Pola opcjonalne obejmują: description, locationId, spotId, gameId, parentEventId (dla podwydarzeń), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Pole image akceptuje {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Maks. 5 MB.

Zwraca {"id": "string"} ze statusem 201.

PUT /events/{eventId}

Aktualizuje istniejące wydarzenie. Taka sama struktura body jak w POST — uwzględnij tylko pola, które chcesz zmienić. Wywołujący musi być organizatorem wydarzenia (konto grupy). Zwraca 202 z pustym body.

GET /events/{eventId}

Pobiera pojedyncze wydarzenie po ID, o tej samej strukturze co elementy w GET /events.

GET /events/{eventId}/children

Zwraca podwydarzenia zagnieżdżone w wydarzeniu nadrzędnym — poszczególne ścieżki tematyczne lub sesje większego spotkania. Każde podwydarzenie ma taką samą strukturę jak zwykłe wydarzenie.

Zarządzanie uczestnikami

Trzy endpointy pozwalają obsługiwać listę uczestników wydarzenia spoza Ludoya — przydatne, jeśli zapisy odbywają się na twojej własnej stronie internetowej, albo importujesz istniejącą listę.

Więcej endpointów

Reszta API w skrócie. Referencja API na stronie publicznego API wymienia każdy endpoint ze wszystkimi polami, a ten sam kontrakt jest opublikowany jako /public/v1/openapi.json oraz jako /public/v1/llms.txt dla asystenta AI, który pisze Twoją integrację. Skopiuj instrukcje dla swojego asystenta AI, na tej samej stronie, daje mu całe API w jednym wklejeniu, bez Twojego klucza.

Dla agentów AI: MCP. Asystent, który mówi Model Context Protocol, łączy się bezpośrednio z /public/v1/mcp tym samym kluczem i może tylko czytać. /public/v1/mcp/write oferuje też narzędzia, które coś zmieniają, więc o tym, czy agent może pisać, decyduje adres, który mu dasz.

• Publikowanie, anulowanie, usuwanie. `POST /events/

GET /members

Zwraca stronicowaną listę członków.

Każdy członek zawiera: id, username, name, avatarUrl, role (OWNER, ADMIN lub MEMBER).

POST /members/invite

Zaprasza kogoś do twojej grupy. Ten endpoint przyjmuje bezpośrednio username — nie trzeba wyszukiwać ID — dzięki czemu możesz dodawać członków bezpośrednio ze swojej strony lub narzędzia administracyjnego.

GET /search/users i GET /search/boardgames

Dwa endpointy wyszukiwania. Większość operacji zapisu wymaga id zamiast nazwy — w ten sposób je uzyskasz.

GET /search/users

GET /search/boardgames

Filtr gier planszowych przyjmuje tę samą, rozdzielaną średnikami formę key=value co filtr kolekcji, więc możesz przeszukiwać katalog po liczbie graczy, czasie rozgrywki, złożoności, roku, wieku lub tagach.

GET /collection

Zwraca twoją kolekcję gier z filtrowaniem, sortowaniem i stronicowaniem.

Odpowiedź: totalGames, totalExpansions, games[] — każdy zawiera: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Zwraca statystyki rozgrywek dla konfigurowalnego okna czasowego.

Odpowiedź zawiera:

• Podsumowanie — łączna liczba rozgrywek, łączny/średni czas rozgrywki, liczba unikalnych gier, graczy i lokalizacji
• Według gracza — liczba rozgrywek na osobę, zwycięstwa, średni i najlepszy wynik
• Według liczby graczy — podział na gry dla 2, 3, 4 graczy itd.
• Według lokalizacji — liczba rozgrywek i liczba unikalnych gier na lokalizację
• Według gry — liczba rozgrywek, łączny/średni czas rozgrywki oraz liczba unikalnych graczy na tytuł

GET /campaigns

Zwraca stronicowaną listę kampanii należących do grupy.

Każda kampania zawiera: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Zwraca pełne szczegóły kampanii należącej do grupy.

Odpowiedź zawiera: Wszystkie pola listy oraz template, description, globalNotes, globalState, members[] (każdy z następującymi polami: user, role, characterNotes, characterState), sessions[] oraz events[].

POST /campaigns

Tworzy kampanię dla grupy. Wymagane pola: gameId i name. Domyślna widoczność to tylko dla członków grupy (ONLY_GROUP), jeśli nie podano.

Pola opcjonalne: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS lub PRIVATE).

Zwraca {"id": "string"} ze statusem 201.

PUT /campaigns/{campaignId}

Aktualizuje istniejącą kampanię. Wszystkie pola są opcjonalne — uwzględnij tylko to, co chcesz zmienić.

Pola opcjonalne: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Zwraca 202 z pustą treścią.

Członkowie kampanii

Zarządzaj tym, kto jest w kampanii, w taki sam sposób, w jaki zarządzasz uczestnikami wydarzenia.

Kody błędów

Pierwsze kroki

1. Wygeneruj klucz API

1. Przejdź na stronę profilu swojej organizacji i dotknij menu (⋮) → Publiczne API albo otwórz Integracje w konsoli i wybierz Klucze i aplikacje
2. Dotknij Wygeneruj klucz
3. Od razu skopiuj klucz — jest pokazywany tylko raz i nie da się go odzyskać

Klucz jest powiązany z twoją organizacją. Zachowaj go w tajemnicy: każdy, kto ma ten klucz, może odczytywać i zapisywać wszystkie powyższe dane.

2. Unieważnij lub wygeneruj ponownie

Aby unieważnić istniejący klucz, wróć na stronę API publiczne i stuknij Unieważnij. Potwierdź okno dialogowe. Każdy system używający starego klucza natychmiast zacznie otrzymywać błędy 401. Aby wygenerować nowy klucz, stuknij ponownie Wygeneruj klucz.

Zobacz także:

• Organizacje — konta organizacji i funkcje premium
• Premium — ceny planów Club i Business
• Integracje — inne sposoby łączenia Ludoya z zewnętrznymi narzędziami