API pública

La API pública da a los administradores de la organización acceso HTTP directo a los datos en vivo de tu organización — llévatelos a cualquier web, app, bot o automatización capaz de hacer una petición HTTP. Es una función del plan Club.

La clave está limitada a tu organización — todos los endpoints trabajan sobre ese grupo automáticamente. URL base: https://api.ludoya.com/public/v1. Cabecera de autenticación: X-Api-Key: TU_CLAVE. Los límites de uso dependen de tu plan: las claves Club permiten 30 peticiones por minuto y 2.000 al día, y las Business 100 por minuto y sin tope diario; al pasarte recibirás un 429.

¿Vas con WordPress? No necesitas tocar la API para nada: el plugin de Ludoya, gratuito, lista tus eventos en tu propio sitio y te deja crearlos y editarlos desde el administrador de WordPress, con la misma clave.

Las claves comienzan con ldy_ y tienen 36 caracteres de longitud, por lo que son fáciles de detectar en un archivo de configuración — y fáciles de escanear si alguna termina donde no debería. Trátala como una contraseña: solo del lado del servidor y revócala desde la misma página si se filtra.

A qué puedes acceder

• Ubicaciones — las ubicaciones disponibles de tu grupo y sus sitios; se usan como entrada al crear eventos
• Eventos (lectura) — eventos próximos y pasados con título, descripción, fecha/hora, zona horaria, capacidad, conteo de participantes y estado
• Eventos (escritura) — crea y actualiza eventos mediante POST y PUT, con control total sobre la ubicación, la capacidad, los permisos, la visibilidad y la imagen
• Subeventos — lista los eventos anidados dentro de un evento principal
• Participantes — agrega a alguien a un evento, cambia su asistencia o elimínalo
• Miembros — lista de miembros con perfiles de usuario y roles (Propietario, Administrador, Miembro), paginada
• Invitaciones — invita a alguien a tu grupo
• Búsqueda — busca usuarios de Ludoya y en el catálogo de juegos de mesa, para poder resolver nombres a ID antes de escribir
• Colección — colección de juegos con filtrado por propiedad, nombre, número de jugadores y lista; ordenable y paginada; cada juego incluye metadatos de BGG
• Estadísticas — estadísticas de partidas para cualquier período: totales, promedios, mejores jugadores con victorias y puntuaciones, desglose por número de jugadores, por ubicación y por juego
• Campañas (lectura) — lista las campañas del grupo con conteos de miembros y sesiones; recupera el detalle completo de la campaña, incluidos los miembros, las sesiones pasadas y los eventos programados
• Campañas (escritura) — crea campañas para el grupo y actualiza su nombre, descripción, estado y visibilidad
• Miembros de la campaña — agrega, actualiza y elimina a las personas en una campaña

Puntos de conexión

GET /locations

Devuelve las ubicaciones disponibles del grupo. Cada ubicación tiene un id, name, address opcional, capacity, un indicador isDefault y una lista spots (cada sitio tiene su propio id, name y capacity). Usa los ID de la ubicación y del sitio al crear eventos.

Inicia sesión con Ludoya

La misma página que contiene tu clave de API también convierte tu organización en un proveedor de inicio de sesión. Permite que la gente acceda a tu propio sitio web, foro o plataforma de comunidad con su cuenta de Ludoya — sin una contraseña aparte que puedan olvidar y sin una base de datos de usuarios que tengas que mantener.

Por qué vale la pena

Cuando alguien aprueba el inicio de sesión, queda vinculado a tu organización: según la política de admisión de tu grupo, o bien se convierte en miembro de inmediato (abierta), envía una solicitud para unirse para que un administrador la apruebe (solicitud para unirse), o simplemente inicia sesión sin unirse (solo con invitación). En cualquiera de los casos, aparece en el endpoint /members como cualquier otra persona — así, el inicio de sesión de tu sitio web y tu lista de miembros de Ludoya se mantienen sincronizados automáticamente.

Cómo configurarlo

Es OpenID Connect estándar, así que la mayoría de las plataformas solo necesitan una URL del emisor más un ID de cliente y su secreto. Registra tu aplicación desde la página de Public API para obtener esas credenciales, y enumera las URI de redirección que usará tu sitio — puedes registrar varias, y cada una debe coincidir con el redirect_uri que envía tu sitio carácter por carácter, incluida la barra final. Un desajuste mínimo es la razón más común por la que falla un primer intento de inicio de sesión.

• Discourse — instala el plugin de OpenID Connect, pega la URL de descubrimiento y añade las credenciales
• WordPress — cualquier plugin genérico de OpenID Connect, usando su opción "auto discover"
• Cualquier otra cosa — si es compatible con OIDC, indícale la URL del emisor y se configurará solo

Cada inicio de sesión devuelve el identificador permanente de la persona, su nombre de usuario, nombre para mostrar y avatar, y su correo electrónico. Las instrucciones completas de configuración, incluido el flujo manual, están en la guía para desarrolladores dentro de la aplicación en Desarrolladores → Iniciar sesión con Ludoya.

Para quienes inician sesión

Cualquier persona que haya usado Ludoya para iniciar sesión en algún sitio puede revisar esas conexiones en Configuración → Aplicaciones conectadas, ver cuándo se conectó y se usó por última vez cada una, y desconectar cualquiera de ellas en cualquier momento. Al desconectar, se corta inmediatamente el acceso del sitio, pero no los elimina de tu grupo.

GET /events

Devuelve eventos futuros y pasados en listas paginadas separadas.

Cada evento incluye: type (MEETUP o PLANNED_PLAY), title, description, startsAt, endsAt, timeZone, imageUrl, capacity, participantCount, canceled, teacher (objeto de usuario o null), master (objeto de usuario o null). Los objetos de usuario contienen id, username, name, avatarUrl.

POST /events

Crea un evento en el grupo. Campos obligatorios: type y title. Si se omite locationId, se usa la ubicación predeterminada del grupo; si no existe, devuelve 400.

Los campos opcionales incluyen: description, locationId, spotId, gameId, parentEventId (para subeventos), startsAt, endsAt, restrictedAttendance, capacity, minParticipants, estimatedDurationMinutes, maxReservationsPerUser, takeGamesPermission, organizePlaysPermission, teacherUserId, masterUserId, visibility, image.

El campo image acepta {"base64": "data:image/jpeg;base64,..."} or {"url": "https://..."}. Máximo 5 MB.

Devuelve {"id": "string"} con estado 201.

PUT /events/{eventId}

Actualiza un evento existente. Mismo formato de cuerpo que POST — incluye solo los campos que quieres cambiar. El solicitante debe ser el organizador del evento (la cuenta del grupo). Devuelve 202 con cuerpo vacío.

GET /events/{eventId}

Obtiene un único evento por ID, con la misma estructura que los elementos de GET /events.

GET /events/{eventId}/children

Devuelve los subeventos anidados dentro de un evento principal — las líneas temáticas o sesiones individuales de un evento de mayor envergadura. Cada subevento tiene la misma estructura que un evento normal.

Gestión de participantes

Tres endpoints te permiten gestionar la lista de asistentes de un evento desde fuera de Ludoya — útil si los registros se hacen en tu propio sitio web, o si estás importando una lista existente.

Más endpoints

El resto de la API, en resumen. La Referencia de la API de la página de la API pública lista cada endpoint con todos sus campos, y el mismo contrato se publica como /public/v1/openapi.json, y como /public/v1/llms.txt para un asistente de IA que escriba tu integración. Copiar las instrucciones para tu asistente de IA, en la misma página, le da toda la API en un solo pegado, sin tu clave.

Para agentes de IA: MCP. Un asistente que hable el Model Context Protocol se conecta directamente a /public/v1/mcp con la misma clave, y solo puede leer. /public/v1/mcp/write ofrece también las herramientas que cambian cosas, así que si un agente puede escribir lo decide la dirección que le das.

• Publicar, cancelar, eliminar. `POST /events/

GET /members

Devuelve una lista paginada de miembros.

Cada miembro incluye: id, username, name, avatarUrl, role (OWNER, ADMIN, o MEMBER).

POST /members/invite

Invita a alguien a tu grupo. Este acepta un username directamente —no hace falta buscar el ID—, por lo que puedes incorporar miembros desde tu propio sitio o herramienta de administración.

GET /search/users y GET /search/boardgames

Los dos endpoints de búsqueda. La mayoría de las operaciones de escritura requieren un id en lugar de un nombre, y con estos puedes obtener uno.

GET /search/users

GET /search/boardgames

El filtro de juegos de mesa usa la misma forma key=value separada por punto y coma que el filtro de la colección, por lo que puedes buscar en el catálogo por número de jugadores, tiempo de juego, complejidad, año, edad o etiquetas.

GET /collection

Devuelve tu colección de juegos con filtrado, ordenación y paginación.

Respuesta: totalGames, totalExpansions, games[] — cada uno con: id, slug, name, imageUrl, isExpansion, yearPublished, minPlayerCount, maxPlayerCount.

GET /stats

Devuelve estadísticas de partidas para una ventana de tiempo configurable.

La respuesta incluye:

• Resumen — partidas totales, tiempo de juego total/promedio, recuentos de juegos, jugadores y ubicaciones únicos
• Por jugador — partidas por persona, victorias, puntuación promedio y mejor puntuación
• Por número de jugadores — desglose de juegos de 2 jugadores, 3 jugadores, 4 jugadores, etc.
• Por ubicación — cantidad de partidas y juegos únicos por lugar
• Por juego — cantidad de partidas, tiempo de juego total/promedio y jugadores únicos por título

GET /campaigns

Devuelve una lista paginada de campañas pertenecientes al grupo.

Cada campaña incluye: id, game (id, name, imageUrl), name, image, status, visibility, createdAt, updatedAt, memberCount, sessionCount.

GET /campaigns/{campaignId}

Devuelve el detalle completo de una campaña perteneciente al grupo.

La respuesta incluye: Todos los campos de la lista, más template, description, globalNotes, globalState, members[] (cada uno con user, role, characterNotes, characterState), sessions[] y events[].

POST /campaigns

Crea una campaña para el grupo. Campos obligatorios: gameId y name. La visibilidad predeterminada es solo para miembros del grupo (ONLY_GROUP) si se omite.

Campos opcionales: templateId, description, visibility (PUBLIC, ONLY_GROUP, ONLY_FRIENDS o PRIVATE).

Devuelve {"id": "string"} con el estado 201.

PUT /campaigns/{campaignId}

Actualiza una campaña existente. Todos los campos son opcionales — incluye solo lo que quieras cambiar.

Campos opcionales: name, description, status (ACTIVE, COMPLETED, ARCHIVED), visibility.

Devuelve 202 con el cuerpo vacío.

Miembros de la campaña

Gestiona quién está en una campaña, de la misma manera que gestionas a los participantes de un evento.

Códigos de error

Primeros pasos

1. Generar una clave de API

1. Ve a la página de perfil de tu organización y toca el menú (⋮) → API pública, o abre Integraciones en la consola y elige Claves y apps
2. Toca Generar clave
3. Copia tu clave enseguida: solo se muestra una vez y no se puede recuperar

La clave está vinculada a tu organización. Mantenla en secreto: cualquiera que tenga la clave puede leer y escribir todos los datos anteriores.

2. Revocar o volver a generar

Para revocar una clave existente, vuelve a la página de API pública y toca Revocar. Confirma el cuadro de diálogo. Cualquier sistema que use la clave antigua comenzará inmediatamente a recibir errores 401. Para emitir una nueva clave, toca Generar clave de nuevo.

Relacionado:

• Organizaciones — cuentas de organización y funciones premium
• Premium — precios de los planes Club y Business
• Integraciones — otras formas de conectar Ludoya con herramientas externas