INTEGRACIÓN

Referencia de la API

Todos los endpoints REST, agrupados por recurso.

URL base y formato

text

https://tu-hostname/api/v1

Todos los endpoints de esta página, salvo /auth/registro y /auth/login, requieren la cabecera Authorization: Bearer <token> (ver Autenticación) y actúan siempre sobre los datos del usuario dueño del token — nunca hace falta (ni es posible) pasar un usuario_id a mano. Las peticiones con cuerpo van en JSON (Content-Type: application/json); la respuesta siempre es JSON, con el sobre {"ok", "data"|"error"} descrito en Primera llamada a la API. Para el detalle de los campos de cada objeto (Nota, Tarea, Categoria...) ver Modelos de datos.

ℹ

¿Vas a importar esta API en Postman, Insomnia, o generar un cliente automáticamente? GET /api/v1/openapi.json devuelve el documento OpenAPI 3.0 completo de todos estos endpoints — generado por introspección del propio código en cada petición (no un archivo aparte que se pueda desincronizar), sin necesitar token: es documentación pública. Las tablas de esta página son la referencia legible; ese JSON es la máquina-legible.

Abrir explorador interactivo

Endpoints filtrables por texto, con parámetros, cuerpo esperado y un curl de ejemplo ya generado.

Método	Ruta	Descripción
GET	/api/v1/openapi.json	Documento OpenAPI 3.0 completo, generado por introspección en cada petición. Sin token.

Manejo de errores

El sobre de error es siempre el mismo, en cualquier endpoint de esta API — incluidos los errores que genera Flask antes de llegar a la vista (404 de ruta inexistente, 405 de método no permitido): {"ok": false, "error": "mensaje legible"}, nunca una página HTML.

HTTP	Significado en esta API
400	Datos de entrada inválidos: campo obligatorio ausente, formato incorrecto, valor fuera de rango.
401	Token ausente, revocado o incorrecto (ver Autenticación).
404	El recurso no existe, o existe pero pertenece a otro usuario — nunca se distingue entre ambos casos, para no filtrar si un id ajeno existe.
405	Método HTTP no soportado para esa ruta.
409	Conflicto — por ejemplo, `/auth/registro` con un email ya registrado.
429	Límite de peticiones superado (solo aplica a `/auth/registro` y `/auth/login`, ver abajo).

⚠

El límite de 10 peticiones/minuto por IP solo se aplica a /auth/registro y /auth/login (protección de fuerza bruta) — el resto de la API no tiene un límite de peticiones propio a nivel de aplicación. Si expones tu instancia a un volumen alto de peticiones automatizadas, añade tu propio límite en Caddy o en el proxy inverso que tengas delante.

ℹ

Notas y tareas con duración no tienen un endpoint GET de listado propio — se leen siempre a través de GET /historial (filtrable por fecha/menú/texto) o de GET /dashboard (resumen del día). Es la misma vía que usa la propia app web: el registro cronológico combinado es el modelo mental central de Guilda Work, no una lista por tipo de objeto. Las tareas estilo Outlook (más abajo) sí tienen su propio GET /tareas-outlook, porque no viven en ese registro cronológico.

Auth

Método	Ruta	Descripción
POST	/auth/registro	Crea una cuenta nueva y devuelve un token.
POST	/auth/login	Inicia sesión y devuelve un token nuevo.
POST	/auth/logout	Revoca el token de la propia petición.
GET	/auth/me	Datos de la cuenta autenticada.

Menús (categorías)

Método	Ruta	Descripción
GET	/categorias	Lista los menús del usuario.
POST	/categorias	Crea un menú nuevo (`nombre`, `color` opcional).
DELETE	/categorias/{id}	Elimina un menú (va a la papelera).
POST	/categorias/{id}/favorito	Alterna si el menú está marcado como favorito.
POST	/categorias/reordenar	Reordena los menús (`orden`: lista de ids).

Notas

Método	Ruta	Descripción
POST	/notas	Crea una nota (`texto`, `categoria_id`).
PUT	/notas/{id}	Edita el texto de una nota.
DELETE	/notas/{id}	Elimina una nota (va a la papelera).

Tareas con duración

No hay un paso de «iniciar» separado: crear una tarea de tipo duracion la deja inmediatamente en curso (inicio_en = ahora, estado = en_curso); crear una de tipo instantanea la crea ya finalizada, sin fin_en/duracion_segundos por diseño (es un evento puntual, no algo que se extiende en el tiempo).

Método	Ruta	Descripción
POST	/tareas	Crea una tarea y la arranca en el mismo paso (`nombre`, `categoria_id`, `tipo`: `duracion`\|`instantanea`).
PUT	/tareas/{id}	Renombra una tarea.
DELETE	/tareas/{id}	Elimina una tarea (va a la papelera).
POST	/tareas/{id}/pausar	Pausa una tarea en curso.
POST	/tareas/{id}/reanudar	Reanuda una tarea pausada.
POST	/tareas/{id}/finalizar	Finaliza la tarea — calcula la duración total descontando el tiempo en pausa.

Tareas estilo Outlook

Un segundo tipo de tarea, independiente de las tareas con duración de arriba — con asunto, cuerpo, prioridad, fechas de inicio/vencimiento y categoría al estilo de Outlook To-Do (pensado para import/export .ics/.csv compatible).

Método	Ruta	Descripción
GET	/tareas-outlook	Lista, filtrable por `estado`/`prioridad`/`categoria`/`q`.
POST	/tareas-outlook	Crea una (`asunto` obligatorio; `cuerpo`, `prioridad`, `fecha_inicio`, `fecha_vencimiento`, `categoria_outlook`).
PUT	/tareas-outlook/{id}	Edita cualquier subconjunto de campos (solo actualiza los presentes en el body).
DELETE	/tareas-outlook/{id}	Elimina.
POST	/tareas-outlook/{id}/completar	Marca como completada.

Dashboard, histórico y exportación

Método	Ruta	Descripción
GET	/dashboard	Resumen del día: menús, tareas activas, notas de hoy, correos sin leer.
GET	/historial	Histórico filtrable por `desde`/`hasta`/`categoria_id`/`q`.
GET	/export	Exporta el histórico — `formato`: `json` (por defecto) \| `csv` \| `md`, más `desde`/`hasta`/`categoria_id`.

Papelera

Método	Ruta	Descripción
GET	/papelera	Lista los elementos borrados (notas, tareas, menús).
POST	/papelera/{tipo}/{id}/restaurar	Restaura un elemento — `tipo`: `nota`\|`tarea`\|`menu`.
POST	/papelera/{tipo}/{id}/eliminar-definitivamente	Borra un elemento sin posibilidad de restaurarlo.

Correo

El cliente de correo propio de Guilda Work (cuentas IMAP/SMTP conectadas por el usuario, distinto del correo-como-herramienta de Stalwart, ver Asistente de IA (MCP)) — bandeja, carpetas, categorías propias, remitentes de confianza, reglas automáticas, firma y envío.

Método	Ruta	Descripción
GET	/correo/cuentas	Lista las cuentas de correo conectadas.
POST	/correo/cuentas	Conecta una cuenta nueva (`host`/`puerto`/`usuario`/`contrasena` IMAP, más SMTP opcional).
DELETE	/correo/cuentas/{id}	Desconecta una cuenta.
POST	/correo/cuentas/{id}/sincronizar	Sincroniza la bandeja (todas las carpetas IMAP se descubren solas).
GET	/correo/carpetas	Carpetas de una cuenta (`cuenta_id`).
GET	/correo/mensajes	Bandeja, filtrable por `cuenta_id`/`carpeta`/`no_leidos`/`q`/`pospuestos`.
GET	/correo/mensajes/{id}	Lee un mensaje completo, con sus adjuntos.
GET	/correo/mensajes/{mensaje_id}/adjuntos/{adjunto_id}	Descarga un adjunto.
DELETE	/correo/mensajes/{id}	Elimina un mensaje.
POST	/correo/mensajes/{id}/leido	Marca leído/no leído.
POST	/correo/mensajes/{id}/destacar	Destaca (y opcionalmente fija una fecha de aviso).
POST	/correo/mensajes/{id}/posponer	Pospone hasta una fecha.
POST	/correo/mensajes/{id}/categoria	Asigna una categoría propia de Guilda Work.
POST	/correo/mensajes/{id}/mover	Mueve a otra carpeta IMAP.
POST	/correo/mensajes/lote/{accion}	Acción en lote sobre varios `ids` a la vez — `accion`: `leido`\|`destacar`\|`mover`\|`eliminar`.
POST	/correo/enviar	Envía un correo (adjuntos en base64, `cc`/`bcc` soportados).
GET / POST	/correo/categorias	Categorías propias de Guilda Work (no se sincronizan con el servidor de correo).
DELETE	/correo/categorias/{id}	Elimina una categoría propia.
GET / POST	/correo/remitentes-confiables	Remitentes cuyas imágenes/enlaces se cargan sin aviso previo.
DELETE	/correo/remitentes-confiables/{id}	Quita un remitente de confianza.
GET / POST	/correo/reglas-categoria	Reglas que asignan categoría automáticamente por patrón de remitente.
DELETE	/correo/reglas-categoria/{id}	Elimina una regla.
GET	/correo/destinatarios-recientes	Autocompletado de destinatarios usados antes (`q`).
GET / POST	/correo/ajustes	Preferencias: densidad, marcar leído automático, límite de mensajes por sincronización.
POST	/correo/firma	Guarda la firma HTML de una cuenta (con o sin firma en respuestas).

Asistente de IA integrado

El chat del asistente embebido en la propia app (distinto de conectar Claude/ChatGPT por MCP contra tu instancia, ver Asistente de IA (MCP) para eso).

Método	Ruta	Descripción
GET	/ia/mensajes	Histórico de la conversación con el asistente.
POST	/ia/mensaje	Envía un mensaje al asistente.
POST	/ia/confirmar	Confirma o cancela una acción sensible pendiente (p. ej. enviar un correo).
POST	/ia/vaciar	Vacía la conversación.
GET / POST	/ia/ajustes	Modelo, modo autónomo y clave de API del proveedor de IA.

Herramientas conectadas

Método	Ruta	Descripción
GET	/herramientas	Catálogo de herramientas conectadas visibles para el usuario (mismo que la pantalla «Herramientas» de la web, sin «Chat» — el móvil usa un cliente Matrix nativo, ver la fila de abajo).
GET	/chat/config	URL del homeserver de Matrix/Synapse, para el cliente de chat nativo.

ℹ

Esta es la API pensada para clientes propios (apps móviles, scripts, integraciones a medida). Para que un asistente de IA de terceros (Claude, ChatGPT, Codex) actúe directamente sobre tu instancia, la vía recomendada es MCP — ver Asistente de IA (MCP).