공개 API는 조직 관리자에게 조직의 실시간 데이터에 대한 직접 HTTP 액세스를 제공합니다 — HTTP 요청을 보낼 수 있는 모든 웹사이트, 앱, 봇, 자동화로 가져올 수 있습니다. 비즈니스 플랜의 기능입니다.
키는 조직에 한정된 범위로 발급됩니다 — 모든 엔드포인트는 자동으로 해당 그룹을 대상으로 동작합니다. 기본 URL: https://api.ludoya.com/public/v1. 인증 헤더: X-Api-Key: YOUR_KEY. 속도 제한: 분당 100회 요청, 초과하면 429를 받습니다.
키는 ldy_로 시작하고 길이는 36자이므로 구성 파일에서 쉽게 눈에 띄며 — 있어서는 안 되는 곳에 노출되더라도 검색하기 쉽습니다. 비밀번호처럼 취급하세요: 서버 측에서만 사용하고, 유출되면 같은 페이지에서 철회하세요.
액세스할 수 있는 항목
- 장소 — 그룹에서 사용 가능한 장소와 그 장소의 자리; 이벤트 생성 시 입력으로 사용됩니다
- 이벤트(읽기) — 제목, 설명, 날짜/시간, 시간대, 정원, 참가자 수, 상태를 포함한 예정 및 지난 이벤트
- 이벤트(쓰기) — POST와 PUT으로 이벤트를 생성 및 업데이트하고, 장소, 정원, 권한, 가시성, 이미지까지 완전한 제어 제공
- 하위 이벤트 — 상위 이벤트에 중첩된 이벤트를 나열합니다
- 참가자 — 이벤트에 누군가를 추가하고 참석 상태를 변경하거나 제거합니다
- 멤버 — 사용자 프로필과 역할(소유자, 관리자, 멤버)이 포함된 멤버 목록, 페이지네이션 지원
- 초대 — 그룹에 누군가를 초대합니다
- 검색 — Ludoya 사용자와 보드게임 카탈로그를 조회하여, 쓰기 전에 이름을 ID로 매핑합니다
- 컬렉션 — 소유 여부, 이름, 플레이어 수, 목록으로 필터링 가능한 보드게임 컬렉션; 정렬 및 페이지네이션 지원; 각 보드게임에는 BGG 메타데이터가 포함됩니다
- 통계 — 임의 기간의 플레이 통계: 합계, 평균, 승수와 점수를 포함한 상위 플레이어, 플레이어 수별 세분화, 장소별, 보드게임별
- 캠페인(읽기) — 멤버 수와 세션 수와 함께 그룹의 캠페인을 나열; 멤버, 지난 세션, 예정된 이벤트를 포함한 전체 캠페인 상세를 조회합니다
- 캠페인(쓰기) — 그룹에 대한 캠페인을 생성하고 이름, 설명, 상태, 가시성을 업데이트합니다
- 캠페인 멤버 — 캠페인에 있는 사람을 추가, 업데이트, 제거합니다
엔드포인트
GET /locations
그룹에서 사용 가능한 장소를 반환합니다. 각 장소에는 id, name, 선택적 address, capacity, isDefault 플래그, 그리고 spots 배열이 있습니다(각 자리는 고유한 id, name, capacity를 가집니다). 이벤트를 생성할 때 장소와 자리 ID를 사용하세요.
Ludoya로 로그인
API 키가 있는 동일한 페이지는 귀하의 조직을 로그인 제공자로도 만들어 줍니다. 사람들은 자신의 Ludoya 계정으로 귀하의 웹사이트, 포럼 또는 커뮤니티 플랫폼에 로그인할 수 있습니다 — 그들에게는 따로 잊어버릴 비밀번호가 필요 없고, 귀하는 사용자 데이터베이스를 운영할 필요가 없습니다.
왜 가치가 있나요
누군가 로그인을 승인하면 그 사람은 귀하의 조직과 연결됩니다. 그룹의 가입 정책에 따라 즉시 멤버가 되거나(공개), 관리자가 승인할 수 있도록 가입 요청을 제출(가입 요청), 또는 가입하지 않고 단순히 로그인만 할 수 있습니다(초대 전용). 어느 경우든 그들은 /members 엔드포인트에 다른 사람들과 마찬가지로 표시되므로 — 귀하의 웹사이트 로그인과 Ludoya 멤버 목록은 자동으로 동기화 상태를 유지합니다.
설정 방법
표준 OpenID Connect이므로 대부분의 플랫폼은 발급자(issuer) URL과 클라이언트 ID, 시크릿만 있으면 됩니다. Public API 페이지에서 애플리케이션을 등록하여 이러한 자격 증명을 받고, 사이트에서 사용할 리디렉트 URI를 나열하세요 — 여러 개를 등록할 수 있으며, 각 항목은 사이트가 보내는 redirect_uri와 마지막 슬래시까지 포함하여 문자 하나까지 정확히 일치해야 합니다. 아주 작은 불일치가 첫 로그인 시도가 실패하는 가장 흔한 이유입니다.
- Discourse — OpenID Connect 플러그인을 설치하고 디스커버리 URL을 붙여넣은 다음 자격 증명을 추가하세요
- WordPress — 어떤 일반 OpenID Connect 플러그인이든 사용하되, "auto discover" 옵션을 사용하세요
- 기타 — OIDC를 지원한다면 발급자 URL을 지정하기만 하면 스스로 구성됩니다
각 로그인에서는 사용자의 영구 식별자, 사용자명, 표시 이름과 아바타, 이메일이 반환됩니다. 수동 절차를 포함한 전체 설정 지침은 앱 내 개발자 가이드의 개발자 → Ludoya로 로그인에 있습니다.
로그인하는 사용자용
Ludoya로 다른 곳에 로그인한 적이 있는 사람은 설정 → 연결된 앱에서 해당 연결들을 검토하고, 각 항목이 언제 연결되었고 마지막으로 언제 사용되었는지 확인하며, 언제든지 연결을 해제할 수 있습니다. 연결을 해제하면 해당 사이트의 액세스는 즉시 중단되지만, 그 사람이 귀하의 그룹에서 제거되지는 않습니다.
GET /events
다가오는 이벤트와 지난 이벤트를 별도의 페이지네이션된 목록으로 반환합니다.
| 매개변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
onlyFuture |
불리언 | true |
지난 이벤트도 반환하려면 false로 설정 |
각 이벤트에는 다음이 포함됩니다: type (MEETUP 또는 PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (사용자 객체 또는 null), master (사용자 객체 또는 null). 사용자 객체에는 id, username, name, avatarUrl가 포함됩니다.
POST /events
그룹에 이벤트를 생성합니다. 필수 필드: type 및 title. locationId가 생략되면 그룹의 기본 장소가 사용됩니다; 존재하지 않으면 400을 반환합니다.
선택 필드에는 다음이 포함됩니다: description, locationId, spotId, gameId, parentEventId(하위 이벤트용), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.
image 필드는 {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."} 중 하나를 허용합니다. 최대 5 MB.
상태 201로 {"id": "string"}을 반환합니다.
PUT /events/{eventId}
기존 이벤트를 업데이트합니다. 본문 구조는 POST와 동일하며, 변경하려는 필드만 포함하면 됩니다. 호출자는 해당 이벤트의 주최자(그룹 계정)여야 합니다. 빈 본문과 함께 202를 반환합니다.
GET /events/{eventId}
id로 단일 이벤트를 가져옵니다. GET /events의 항목과 동일한 구조입니다.
GET /events/{eventId}/children
상위 이벤트에 포함된 하위 이벤트를 나열합니다 — 더 큰 행사의 개별 트랙 또는 세션입니다. 각 하위 이벤트는 일반 이벤트와 동일한 구조를 가집니다.
참가자 관리
세 가지 엔드포인트로 Ludoya 외부에서 이벤트의 참석자 명단을 운영할 수 있습니다 — 등록이 본인 웹사이트에서 이뤄지거나 기존 명단을 가져오는 경우에 유용합니다.
| 메서드 | 경로 | 설명 |
|---|---|---|
POST |
`/events/ |
GET /members
페이지네이션된 회원 목록을 반환합니다.
| 매개변수 | 유형 | 기본값 |
|---|---|---|
pagination.size |
int | 50 |
pagination.offset |
int | 0 |
각 회원에 포함되는 항목: id, username, name, avatarUrl, role (OWNER, ADMIN, 또는 MEMBER).
POST /members/invite
그룹에 사용자를 초대합니다. 이 엔드포인트는 **username**을 직접 받으므로 id를 조회할 필요가 없으며, 자체 사이트나 관리 도구에서 바로 회원을 추가할 수 있습니다.
GET /search/users 및 GET /search/boardgames
두 가지 조회 엔드포인트입니다. 대부분의 쓰기 작업은 이름이 아니라 id를 필요로 하며, 이 엔드포인트들로 id를 얻을 수 있습니다.
GET /search/users
| 매개변수 | 유형 | 기본값 |
|---|---|---|
query |
문자열 | 필수 |
intent |
문자열 | — |
pagination.size |
정수 | 20 |
pagination.offset |
정수 | 0 |
GET /search/boardgames
| 매개변수 | 유형 | 기본값 |
|---|---|---|
query |
문자열 | 필수 |
filter |
문자열 | — |
pagination.size |
정수 | 50 |
pagination.offset |
정수 | 0 |
보드게임 필터는 컬렉션 필터와 동일한 세미콜론으로 구분된 key=value 형식을 사용하므로, 플레이어 수, 플레이 시간, 복잡도, 연도, 연령 또는 태그로 카탈로그를 검색할 수 있습니다.
GET /collection
필터링, 정렬 및 페이지네이션을 통해 사용자의 보드게임 컬렉션을 반환합니다.
| 매개변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
filter |
string | — | 세미콜론으로 구분된 key=value 쌍입니다. 키: ownership (OWNED, PREVIOUSLY_OWNED, PREORDERED, WISHLISTED), played (boolean), listId, nameFilter, playerCountFilterType (OFFICIAL, GOOD, BEST), playerCountFilter (number) |
groupExpansions |
boolean | true |
확장팩을 기본 보드게임 아래로 그룹화합니다 |
sort |
string | — | 형식: property,direction — 예: name,asc |
pagination |
string | — | 형식: size,pageIndex — 예: 20,0 |
응답: totalGames, totalExpansions, games[] — 각 항목에는: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.
GET /stats
설정 가능한 기간에 대한 플레이 통계를 반환합니다.
| 매개변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
period |
문자열 | ALL_TIME | 형식: PERIOD,date,index. 값: ALL_TIME, ONE_YEAR, ONE_MONTH, THIRTY_DAYS, SEVEN_DAYS, ONE_DAY, CUSTOM. index는 기간을 뒤로 이동합니다(0 = 현재, 1 = 이전). 사용자 지정: CUSTOM,startDate,0,endDate |
응답에는 다음이 포함됩니다:
- 요약 — 총 플레이 수, 총/평균 플레이 시간, 고유 보드게임 수, 고유 플레이어 수, 고유 장소 수
- 플레이어별 — 개인별 플레이 수, 승리 수, 평균 및 최고 점수
- 플레이어 수별 — 2인용, 3인용, 4인용 보드게임 등으로 세분화
- 장소별 — 플레이 수 및 고유 보드게임 수
- 보드게임별 — 플레이 수, 총/평균 플레이 시간, 고유 플레이어 수
GET /campaigns
그룹에 속한 캠페인 목록을 페이지 단위로 반환합니다.
| 매개변수 | 유형 | 기본값 | 설명 |
|---|---|---|---|
status |
string | — | 상태로 필터링: ACTIVE, COMPLETED, 또는 ARCHIVED |
pagination.size |
int | 50 | 페이지당 항목 수 |
pagination.offset |
int | 0 | 오프셋 |
각 캠페인에는 다음이 포함됩니다: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.
GET /campaigns/{campaignId}
그룹에 속한 캠페인의 전체 세부 정보를 반환합니다.
응답에는 다음이 포함됩니다: 모든 목록 필드와 template, description, globalNotes, globalState, members[] (각 항목에 user, role, characterNotes, characterState 포함), sessions[], 그리고 events[].
POST /campaigns
그룹용 캠페인을 생성합니다. 필수 필드: gameId 및 name. 생략된 경우 가시성은 그룹 구성원 전용(ONLY_GROUP)이 기본값입니다.
선택 필드: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS, 또는 PRIVATE).
상태 201과 함께 {"id": "string"}를 반환합니다.
PUT /campaigns/{campaignId}
기존 캠페인을 업데이트합니다. 모든 필드는 선택 사항이며, 변경하려는 항목만 포함하면 됩니다.
선택 필드: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.
빈 본문과 함께 202를 반환합니다.
캠페인 구성원
이벤트 참가자를 관리하는 것과 동일한 방식으로, 캠페인에 누가 속해 있는지 관리합니다.
| 메서드 | 경로 | 설명 |
|---|---|---|
POST |
`/campaigns/ |
오류 코드
| 상태 | 발생 시점 |
|---|---|
| 400 | 유효성 검사 실패(필수 필드 누락, 위치를 찾을 수 없음, 잘못된 이미지) |
| 401 | API 키가 없거나 유효하지 않음 |
| 403 | 허용되지 않은 작업이거나 그룹이 Business 플랜이 아님 |
| 404 | 리소스를 찾을 수 없음 |
| 429 | 요청 한도 초과 |
시작하기
1. API 키 생성
- 조직의 프로필 페이지로 이동합니다
- 메뉴(⋮) → 공개 API를 누릅니다
- 키 생성을 누릅니다
- 키를 즉시 복사하세요 — 한 번만 표시되며 다시 확인할 수 없습니다
키는 조직에 연결됩니다. 비밀로 유지하세요. 키를 가진 사람은 위의 모든 데이터를 읽고 쓸 수 있습니다.
2. 폐기 또는 재생성
기존 키를 폐기하려면 공개 API 페이지로 돌아가 폐기를 누르세요. 대화 상자를 확인합니다. 이전 키를 사용하던 모든 시스템은 즉시 401 오류를 받기 시작합니다. 새 키를 발급하려면 키 생성을 다시 누르세요.
관련: