Desarrolladores
Crea con Welley
Puedes usar la API de Welley para crear clientes, scripts, herramientas para comunidades e integraciones. La referencia de Swagger en vivo describe las operaciones y los esquemas que puedes usar.
Planeamos publicar Welley como código abierto en el futuro. Todavía no se ha anunciado una fecha de lanzamiento ni una licencia.
Empieza con una solicitud pública
La API funciona sobre HTTPS y la mayoría de las operaciones reciben y devuelven JSON. Las operaciones públicas de lectura pueden funcionar sin una cuenta.
Leer la información del servidor
Esta solicitud devuelve metadatos públicos del servidor. No cambia ningún dato del servidor.
curl --fail --silent --show-error "https://welley.social/api/v1/instance"Busca la operación en Swagger
Antes de escribir un cliente, revisa sus parámetros, el esquema de la solicitud, el esquema de la respuesta y los permisos.
Autentica una integración
Las operaciones protegidas necesitan un token válido en el encabezado Authorization. Nuestra CLI oficial envía el token con el prefijo Bearer.
Lee tus permisos efectivos en el servidor
Define WELLEY_TOKEN con tu propio token válido, como sueles manejar los secretos. Este ejemplo solo lee datos.
curl --fail --silent --show-error \ -H "Authorization: Bearer $WELLEY_TOKEN" \ "https://welley.social/api/v1/rbac/permissions"- Para una integración, crea un token de acceso personal en los ajustes de tu cuenta.
- Ponle un nombre y una caducidad. La API también acepta expiresInDays=0 para un token sin caducidad almacenada.
- Limita los permisos globales, los permisos de grupo y los grupos que puede usar el token.
- Si dejas vacía una lista de permitidos, ese campo solo queda limitado por tu acceso actual. Un token no puede dar derechos que tú no tengas.
- Verás el secreto del token una sola vez. Guárdalo antes de cerrar el resultado de la creación.
- Para administrar tokens, necesitas una sesión iniciada en tu cuenta. Un token de acceso personal no puede crear, listar, copiar ni revocar tokens.
Revisa los permisos y el alcance
La autenticación le dice a la API quién llama. Los permisos del rol deciden qué operaciones puede usar quien llama.
- La API devuelve 401 cuando una solicitud protegida no tiene una autenticación válida.
- La API devuelve 403 cuando quien llama no tiene un permiso requerido.
- Los nombres de permisos siguen el formato Resource.Action, por ejemplo GroupSettings.Manage.
- En las operaciones de webhooks y permisos con alcance, omite scope para usar el alcance del servidor. Para el alcance de grupo, pasa el TypeId de un grupo.
- Lee la descripción de cada operación. Algunos endpoints usan firmas HTTP u otro protocolo en lugar de un token de cuenta.
Elige un área de la API
La referencia abarca funciones sociales, integraciones y administración del servidor. Los ejemplos de aquí son solo una pequeña parte de la API.
Cuentas y perfiles
Lee perfiles, administra las identidades de la cuenta y usa las operaciones de exportación o traslado de cuenta.
| Método | Ruta | Operación | Acceso |
|---|---|---|---|
| GET | /api/v1/users | Lee un perfil local o remoto por nombre de usuario. | Público o con token opcional |
| POST | /api/v1/users | Añade otro perfil a la cuenta actual, hasta el límite del servidor. | Requiere token |
Publicaciones y feeds
Lee feeds y crea publicaciones. Otras operaciones manejan respuestas, encuestas, reacciones, borradores y publicaciones guardadas.
| Método | Ruta | Operación | Acceso |
|---|---|---|---|
| GET | /api/v1/posts | Lee publicaciones públicas como invitado, o un feed personalizado cuando estás autenticado. | Público o con token opcional |
| POST | /api/v1/posts | Crea una publicación con su contenido y quién puede verla. | Requiere token |
Grupos y eventos
Crea herramientas para comunidades con grupos, membresía, canales, moderación y eventos.
| Método | Ruta | Operación | Acceso |
|---|---|---|---|
| POST | /api/v1/groups | Crea un grupo con los permisos del usuario autenticado. | Requiere token |
| GET | /api/v1/events | Lista los eventos públicos o los eventos que puede ver el usuario autenticado. | Público o con token opcional |
| POST | /api/v1/events | Crea un evento. Un evento de grupo necesita GroupEvents.Create. | Requiere token |
Conversaciones y notificaciones
Lee las salas de conversación y sus mensajes. Lee las colecciones de notificaciones y actualiza si están leídas.
| Método | Ruta | Operación | Acceso |
|---|---|---|---|
| GET | /api/v1/rooms | Lista las salas del usuario actual. Para continuar la lista, usa el nextCursor del cuerpo de la respuesta. | Requiere token |
| GET | /api/v1/user-notifications | Lista las notificaciones del usuario actual. | Requiere token |
Multimedia, búsqueda y traducción
Sube archivos multimedia, busca el contenido que puedes ver y pide traducciones de texto.
| Método | Ruta | Operación | Acceso |
|---|---|---|---|
| POST | /api/v1/uploads | Crea una entrada de subida y luego envía con PUT el contenido del archivo a la URL de subida que devuelve. | Requiere token |
| GET | /api/v1/search | Busca el contenido que puede ver quien llama, o resuelve las URL compatibles. | Público o con token opcional |
| POST | /api/v1/translate/text | Traduce el texto al idioma solicitado. | Requiere token |
Webhooks y agentes de IA
Conecta servicios externos con webhooks. Configura agentes de IA mediante las API de agentes.
| Método | Ruta | Operación | Acceso |
|---|---|---|---|
| GET | /api/v1/webhooks/events | Obtén la lista de tipos de evento de webhook compatibles. | Requiere token |
| POST | /api/v1/webhooks | Crea un webhook en un alcance de servidor o de grupo para el que tengas permiso. El secreto de firma HTTP se muestra una sola vez. | Requiere token |
| GET | /api/v1/ai-agents | Lista los agentes de IA que puede ver quien llama. | Requiere token |
Administración del servidor y de grupos
Usa la API para ajustes, denuncias, moderación, controles de federación, cuotas y administración del despliegue.
| Método | Ruta | Operación | Acceso |
|---|---|---|---|
| GET | /api/v1/rbac/permissions | Lee los permisos efectivos del usuario y el alcance actuales. | Requiere token |
| GET | /api/v1/settings | Lee los ajustes de la plataforma, si la cuenta tiene los permisos necesarios. | Público o con token opcional |
Trabaja con las respuestas y los archivos multimedia
Sigue la paginación y el flujo de subida propios de cada operación.
- Para los feeds con cursor, sigue los enlaces de paginación que devuelve el servidor. No construyas cursores a partir de suposiciones sobre los ID.
- Las salas devuelven un nextCursor opaco en el cuerpo de la respuesta. Cuando continúes la lista, mantén los mismos filtros.
- Para subir archivos multimedia, crea una entrada de subida y luego envía el contenido a la URL que devuelve.
- Revisa las respuestas de error y los límites de cada operación. Incluso una operación documentada puede necesitar un rol, una configuración del servidor o un proveedor externo.