Offentligt API

Offentligt API ger organisationsadministratörer direkt HTTP-åtkomst till din organisations levande data — hämta in den i vilken webbplats, app, bot eller automation som helst som kan göra en HTTP-förfrågan. Det är en funktion i Business-planen.

Nyckeln är begränsad till din organisation — alla ändpunkter arbetar automatiskt mot den gruppen. Bas-URL: https://api.ludoya.com/public/v1. Autentiseringshuvud: X-Api-Key: YOUR_KEY. Hastighetsgräns: 100 förfrågningar per minut, därefter får du en 429.

Nycklar börjar med ldy_ och är 36 tecken långa, så de är lätta att få syn på i en konfigurationsfil — och lätta att söka efter om en någon gång hamnar där den inte ska. Behandla den som ett lösenord: bara på serversidan, och återkalla den från samma sida om den läcker.

Vad du kommer åt

• Platser — din grupps tillgängliga lokaler och deras platser; används som indata när du skapar evenemang
• Evenemang (läs) — kommande och tidigare evenemang med titel, beskrivning, datum/tid, tidszon, kapacitet, deltagarantal och status
• Evenemang (skriv) — skapa och uppdatera evenemang via POST och PUT, med full kontroll över plats, kapacitet, behörigheter, synlighet och bild
• Underarrangemang — lista evenemangen som ligger inuti ett överordnat evenemang
• Deltagare — lägg till någon i ett evenemang, ändra deras närvaro eller ta bort dem
• Medlemmar — medlemslista med användarprofiler och roller (Ägare, Administratör, Medlem), paginerad
• Inbjudningar — bjud in någon till din grupp
• Sök — slå upp Ludoya-användare och brädspelskatalogen, så att du kan omvandla namn till ID:n innan du skriver
• Samling — spelsamling med filtrering på ägande, namn, antal spelare och lista; sorterbar och paginerad; varje spel innehåller BGG-metadata
• Statistik — spelstatistik för valfri tidsperiod: totaler, genomsnitt, toppspelare med vinster och poäng, uppdelningar per antal spelare, per plats och per spel
• Kampanjer (läs) — lista gruppens kampanjer med antal medlemmar och sessioner; hämta fullständig kampanjinformation inklusive medlemmar, tidigare sessioner och schemalagda evenemang
• Kampanjer (skriv) — skapa kampanjer för gruppen och uppdatera deras namn, beskrivning, status och synlighet
• Kampanjmedlemmar — lägg till, uppdatera och ta bort personerna i en kampanj

Ändpunkter

GET /locations

Returnerar gruppens tillgängliga platser. Varje plats har ett id, name, valfri address, capacity, en isDefault-flagga och en spots-array (varje plats har sitt eget id, name och capacity). Använd plats- och spot-ID:n när du skapar evenemang.

Logga in med Ludoya

Samma sida som håller din API-nyckel gör också din organisation till en inloggningsleverantör. Låt folk logga in på din egen webbplats, ditt forum eller din communityplattform med sitt Ludoya-konto — inget separat lösenord för dem att glömma, och ingen användardatabas för dig att driva.

Varför det är värt det

När någon godkänner inloggningen kopplas de till din organisation: beroende på din grupps policy för medlemskap blir de medlem direkt (öppen), skickar en medlemsförfrågan som en administratör godkänner (ansökan krävs), eller loggar helt enkelt in utan att gå med (endast inbjudan). Hur som helst dyker de upp i /members-ändpunkten som vem som helst — så din webbplats inloggning och din Ludoya-medlemslista hålls i takt automatiskt.

Att ställa in det

Det är vanlig OpenID Connect, så de flesta plattformar behöver inget mer än en issuer-URL plus ett client ID och en hemlighet. Registrera din applikation från sidan för Offentligt API för att få de uppgifterna, och lista de redirect-URI:er din sajt kommer att använda — du kan registrera flera, och var och en måste matcha den redirect_uri din sajt skickar tecken för tecken, avslutande snedstreck inräknat. En nästan-träff är den enskilt vanligaste orsaken till att ett första inloggningsförsök misslyckas.

• Discourse — installera OpenID Connect-tillägget, klistra in discovery-URL:en, lägg till uppgifterna
• WordPress — vilket generiskt OpenID Connect-tillägg som helst, med dess "auto discover"-alternativ
• Allt annat — om det talar OIDC, peka det mot issuer-URL:en så konfigurerar det sig självt

Varje inloggning returnerar personens permanenta identifierare, deras användarnamn, visningsnamn och avatar, samt deras e-post. Fullständiga installationsanvisningar, inklusive flödet för hand, finns i utvecklarguiden i appen under Developers → Sign in with Ludoya.

För dem som loggar in

Alla som har använt Ludoya för att logga in någonstans kan granska de kopplingarna under Inställningar → Anslutna appar, se när var och en kopplades och senast användes, och koppla från vilken som helst när som helst. Att koppla från stänger av sajtens åtkomst omedelbart men tar inte bort dem från din grupp.

GET /events

Returnerar framtida och tidigare evenemang i separata paginerade listor.

Varje evenemang innehåller: type (MEETUP eller PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (användarobjekt eller null), master (användarobjekt eller null). Användarobjekt innehåller id, username, name, avatarUrl.

POST /events

Skapar ett evenemang i gruppen. Obligatoriska fält: type och title. Om locationId utelämnas används gruppens standardplats; om ingen finns returneras 400.

Valfria fält inkluderar: description, locationId, spotId, gameId, parentEventId (för underarrangemang), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

Fältet image tar emot antingen {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Max 5 MB.

Returnerar {"id": "string"} med status 201.

PUT /events/{eventId}

Uppdaterar ett befintligt evenemang. Samma kroppsstruktur som POST — ta bara med de fält du vill ändra. Anroparen måste vara evenemangets arrangör (gruppkontot). Returnerar 202 med tom kropp.

GET /events/{eventId}

Hämtar ett enskilt evenemang via id, med samma struktur som posterna i GET /events.

GET /events/{eventId}/children

Listar underevenemangen inuti ett överordnat evenemang — de enskilda spåren eller sessionerna i ett större arrangemang. Varje underevenemang har samma struktur som ett vanligt evenemang.

Hantera deltagare

Tre ändpunkter låter dig sköta ett evenemangs deltagarlista utanför Ludoya — praktiskt om anmälningar sker på din egen webbplats, eller om du importerar en befintlig lista.

GET /members

Returnerar en paginerad medlemslista.

Varje medlem innehåller: id, username, name, avatarUrl, role (OWNER, ADMIN, eller MEMBER).

POST /members/invite

Bjuder in någon till din grupp. Den här tar emot ett username direkt – ingen id-uppslagning behövs – så du kan lägga till medlemmar direkt från din egen webbplats eller ditt adminverktyg.

GET /search/users and GET /search/boardgames

De två uppslagsändpunkterna. De flesta skrivoperationer vill ha ett id snarare än ett namn, och det är så här du får ett.

GET /search/users

GET /search/boardgames

Brädspelsfiltret tar samma semikolonseparerade key=value-form som samlingsfiltret, så du kan söka i katalogen på antal spelare, speltid, komplexitet, år, ålder eller taggar.

GET /collection

Returnerar din spelsamling med filtrering, sortering och paginering.

Svar: totalGames, totalExpansions, games[] — var och en med: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Returnerar spelstatistik för ett konfigurerbart tidsfönster.

Svaret innehåller:

• Sammanfattning — totalt antal spelomgångar, total/genomsnittlig speltid, antal unika spel, spelare och platser
• Per spelare — spelomgångar, vinster, genomsnittlig och bästa poäng per person
• Per antal spelare — uppdelning på 2-spelar-, 3-spelar-, 4-spelarspel osv.
• Per plats — antal spelomgångar och unika spel per lokal
• Per spel — antal spelomgångar, total/genomsnittlig speltid och unika spelare per titel

GET /campaigns

Returnerar en paginerad lista över kampanjer som tillhör gruppen.

Varje kampanj innehåller: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Returnerar den fullständiga informationen om en kampanj som tillhör gruppen.

Svaret innehåller: Alla listfält, plus template, description, globalNotes, globalState, members[] (var och en med user, role, characterNotes, characterState), sessions[] och events[].

POST /campaigns

Skapar en kampanj för gruppen. Obligatoriska fält: gameId och name. Synligheten är som standard endast gruppmedlemmar (ONLY_GROUP) om den utelämnas.

Valfria fält: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS eller PRIVATE).

Returnerar {"id": "string"} med status 201.

PUT /campaigns/{campaignId}

Uppdaterar en befintlig kampanj. Alla fält är valfria — ta bara med det du vill ändra.

Valfria fält: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Returnerar 202 med tom kropp.

Kampanjmedlemmar

Hantera vilka som är med i en kampanj, på samma sätt som du hanterar deltagare i ett evenemang.

Felkoder

Kom igång

1. Generera en API-nyckel

1. Gå till din organisations profilsida
2. Tryck på menyn (⋮) → Offentligt API
3. Tryck på Generera nyckel
4. Kopiera din nyckel omedelbart — den visas bara en gång och kan inte hämtas igen

Nyckeln är knuten till din organisation. Håll den hemlig: den som har nyckeln kan läsa och skriva alla data ovan.

2. Återkalla eller generera på nytt

För att återkalla en befintlig nyckel, gå tillbaka till sidan Offentligt API och tryck på Återkalla. Bekräfta dialogrutan. Alla system som använder den gamla nyckeln börjar omedelbart få 401-fel. För att utfärda en ny nyckel, tryck på Generera nyckel igen.

Relaterat:

• Organisationer — organisationskonton och premiumfunktioner
• Premium — priser för Business-planen
• Integrationer — andra sätt att koppla Ludoya till externa verktyg