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.

[Abrir Swagger UI en vivo](https://welley.social/q/swagger-ui/) [Descargar el JSON de OpenAPI](https://welley.social/q/openapi?format=json)

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.