Referencia de API de Neotask

Referencia completa de la API para la plataforma Neotask. Este documento cubre cada endpoint disponible, metodos de autenticacion, manejo de errores y limites de tasa.

Autenticacion

Todas las solicitudes API requieren autenticacion mediante uno de los siguientes metodos:

Muchos endpoints combinan multiples requisitos de autenticacion. Por ejemplo, "Tenant + Admin" significa que la solicitud debe incluir tanto un JWT valido (perteneciente a un usuario con el rol de Admin) como el encabezado x-tenant-id.

Endpoints de Auth

Endpoints para autenticacion de usuarios en plataformas web, iOS y escritorio.

Metodo Endpoint Descripcion Auth
POST /api/auth/login Autenticar con correo y contrasena. Devuelve un JWT en caso de exito. Ninguna
POST /api/auth/google Autenticar via Google OAuth en la web. Espera un codigo de autorizacion de Google. Ninguna
POST /api/auth/google-ios Autenticar via Google OAuth en iOS. Espera un payload de autorizacion especifico de iOS. Ninguna
POST /api/auth/google-token Verificar un token de acceso de Google y devolver un JWT de Neotask. Ninguna
POST /api/auth/apple Autenticar via Apple Sign-In. Espera un token de identidad de Apple. Ninguna
GET /api/auth/me Devolver el perfil del usuario autenticado (nombre, correo, avatar, roles). JWT
DELETE /api/auth/account Eliminar permanentemente la cuenta del usuario autenticado y todos los datos asociados. JWT

Endpoints de Auth del Panel

Endpoints de autenticacion especificos del panel de Neotask, incluyendo inicio de sesion con clave de licencia y autenticacion de dos factores (TOTP).

Metodo Endpoint Descripcion Auth
POST /api/dashboard/auth/login Autenticar con una clave de licencia. Devuelve un JWT en caso de exito, o senala que se requiere TOTP. Ninguna
POST /api/dashboard/auth/totp-login Completar inicio de sesion proporcionando un codigo TOTP o codigo de respaldo cuando la autenticacion de dos factores esta habilitada. Ninguna
GET /api/dashboard/auth/me Devolver la informacion de licencia actual y los derechos de funciones para el usuario autenticado del panel. JWT
POST /api/dashboard/totp/setup Generar un secreto TOTP y codigo QR para configurar la autenticacion de dos factores. JWT
POST /api/dashboard/totp/verify Verificar un codigo TOTP para confirmar y habilitar la autenticacion de dos factores en la cuenta. JWT

Endpoints de Facturacion

Gestionar suscripciones, sesiones de checkout y compras in-app a traves de Stripe y RevenueCat.

Metodo Endpoint Descripcion Auth
POST /api/billing/checkout Crear una sesion de Stripe Checkout para el plan Pro. Devuelve una URL de checkout. Tenant + Admin
POST /api/billing/checkout/enterprise Crear una sesion de Stripe Checkout para el plan Enterprise. Devuelve una URL de checkout. Tenant + Admin
GET /api/billing/status Devolver el plan actual, conteo de mensajes y limites de uso para el inquilino. Tenant + Viewer
POST /api/billing/portal Crear una sesion del Portal de Cliente de Stripe para gestionar metodos de pago y facturas. Tenant + Admin
POST /api/billing/agent-addon Comprar un complemento de espacio de agente adicional para el inquilino. Tenant + Admin
POST /api/billing/webhook Manejador de webhook de Stripe. Valida la firma de Stripe y procesa eventos del ciclo de vida de suscripciones. Stripe Signature
POST /api/billing/revenuecat-sync Verificar una compra in-app de iOS via RevenueCat y sincronizar derechos al inquilino. Tenant + Admin
POST /api/billing/revenuecat-webhook Manejador de webhook de RevenueCat. Procesa eventos de suscripcion originados desde el App Store. Bearer

Endpoints de Chat

Enviar y recibir mensajes, gestionar sesiones y consultar resultados de trabajos asincronos.

Metodo Endpoint Descripcion Auth
POST /api/chat/init Auto-provisionar un inquilino, agente y sesion para el usuario autenticado. Use esto para inicializar el entorno de chat de un nuevo usuario en una sola llamada. JWT
POST /api/chat/send Enviar un mensaje al agente. El mensaje se procesa asincronamente; se devuelve un ID de trabajo inmediatamente. Tenant + Admin
GET /api/chat/jobs/:jobId Consultar el estado y resultado de un trabajo de chat asincrono por su ID. Tenant + Viewer
GET /api/chat/messages Obtener todos los mensajes para una sesion dada. Pase el ID de sesion como parametro de consulta. Tenant + Viewer
GET /api/chat/sessions Listar todas las sesiones de chat del inquilino. Tenant + Viewer
POST /api/chat/sessions Crear una nueva sesion de chat. Tenant + Admin

Endpoints de Agentes y Actividad

Explorar agentes, sesiones, herramientas, archivos, skills, canales, trabajos programados y equipos asociados al inquilino.

Metodo Endpoint Descripcion Auth
GET /api/activity/agents Listar todos los agentes pertenecientes al inquilino. Tenant
GET /api/activity/sessions Listar sesiones. Soporta filtrado por agentId, status y parametros de rango de fechas. Tenant
GET /api/activity/sessions/:id/entries Obtener todas las entradas (mensajes y eventos) para una sesion especifica. Tenant
GET /api/activity/tools Listar todas las herramientas disponibles para los agentes del inquilino. Tenant
GET /api/activity/files Listar todos los archivos asociados con los agentes del inquilino. Tenant
GET /api/activity/skills Listar todos los skills asociados con los agentes del inquilino. Tenant
GET /api/activity/channels Listar todos los canales asociados con los agentes del inquilino. Tenant
GET /api/activity/cron-jobs Listar todos los trabajos programados (cron) del inquilino. Tenant
GET /api/activity/teams Listar todos los equipos dentro del inquilino. Tenant

Endpoints de Skills

Gestionar el catalogo de skills, instalar y configurar skills, y publicar skills personalizados.

Metodo Endpoint Descripcion Auth
GET /api/skills/catalog Explorar el catalogo completo de skills. Devuelve todos los skills publicados disponibles para instalacion. Tenant
GET /api/skills/list Listar los skills actualmente instalados por el usuario. Tenant + Viewer
POST /api/skills/sync Sincronizar skills desde el sistema de archivos. Use esto despues de desplegar nuevos archivos de skills para actualizar el registro. Tenant + Admin
POST /api/skills/register Registrar (instalar) un skill del catalogo. Tenant + Viewer
DELETE /api/skills/register/:skillId Desregistrar (desinstalar) un skill por su ID. Tenant + Viewer
POST /api/skills/:skillId/publish Publicar un skill para hacerlo disponible en el catalogo. Tenant + Admin
POST /api/skills/:skillId/unpublish Despublicar un skill, eliminandolo del catalogo. Tenant + Admin
GET /api/skills/all Listar todos los skills incluyendo los no publicados. Endpoint solo para admin para gestion de skills. Tenant + Admin
PUT /api/skills/:skillId/env-schema Definir o actualizar el esquema de variables de entorno para un skill. Esto controla que campos de configuracion se presentan a los usuarios. Tenant + Admin
POST /api/skills/:skillId/configure Guardar valores de configuracion para un skill instalado. Tenant + Viewer
DELETE /api/skills/:skillId/configure Eliminar toda la configuracion de un skill, restableciendolo a valores predeterminados. Tenant + Viewer

Endpoints de Canales

Vincular, configurar, habilitar y desconectar canales de mensajeria (por ejemplo, Slack, Discord, WhatsApp).

Metodo Endpoint Descripcion Auth
GET /api/channels/ Listar todos los canales y sus estados actuales. Tenant + Viewer
GET /api/channels/:channel/status Obtener el estado detallado de un canal especifico. Tenant + Viewer
POST /api/channels/:channel/link Iniciar el proceso de vinculacion para un canal. Devuelve una URL de vinculacion o token de sesion dependiendo del tipo de canal. Tenant + Admin
GET /api/channels/:channel/link/wait Long-poll para la finalizacion de un flujo de vinculacion de canal. Devuelve una vez que el canal se vincula exitosamente o la operacion expira. Tenant + Admin
GET /api/channels/:channel/jobs/:jobId Obtener el resultado de un trabajo asincrono especifico del canal. Tenant + Admin
POST /api/channels/:channel/enable Habilitar un canal vinculado para que el agente comience a recibir mensajes de el. Tenant + Admin
POST /api/channels/:channel/disable Deshabilitar un canal sin desvincularlo. El agente deja de recibir mensajes pero la conexion del canal se preserva. Tenant + Admin
POST /api/channels/:channel/disconnect Desconectar y desvincular completamente un canal. Tenant + Admin
GET /api/channels/:channel/config Obtener la configuracion actual de un canal. Tenant + Admin
POST /api/channels/:channel/config Actualizar la configuracion de un canal. Tenant + Admin

Endpoints de Google OAuth

Iniciar y gestionar flujos de Google OAuth para conectar servicios de Google a Neotask.

Metodo Endpoint Descripcion Auth
GET/POST /oauth/google/start Iniciar un flujo de Google OAuth. Acepta parametros opcionales para especificar a que servicios de Google solicitar acceso. Opcional
GET /oauth/google/services Listar todas las definiciones de servicios de Google soportados por Neotask, agrupados por categoria. Ninguna
GET /oauth/google/callback Manejador de callback OAuth. Google redirige aqui despues de que el usuario otorga o deniega acceso. Ninguna
GET /oauth/google/status Consultar el estado de un flujo OAuth en progreso. Devuelve si el flujo esta pendiente, completado o fallido. Ninguna

Servicios de Google Disponibles

Neotask soporta la conexion a 25 servicios de Google, organizados por categoria:

Categoria Servicios
Core Gmail, Calendar, Drive, Docs, Sheets, Slides, Forms, Keep, Tasks
Comunicacion People/Contacts, Chat, Meet, YouTube, Photos
Ubicacion Places API, Routes/Directions, Business Profile
Especializados Classroom, Play Developer, AdSense, Google Ads

Endpoints de Claves de Proveedor

Gestionar claves API de terceros (por ejemplo, para proveedores de LLM). Las claves se cifran en reposo y pueden resolverse (descifrarse) bajo demanda.

Metodo Endpoint Descripcion Auth
PUT /api/provider-keys/:provider Guardar o actualizar una clave API para el proveedor especificado. La clave se cifra antes del almacenamiento. HMAC + Auth
GET /api/provider-keys/ Listar todas las claves de proveedor guardadas. Los valores de las claves estan enmascarados (solo se muestran los ultimos cuatro caracteres). Auth
DELETE /api/provider-keys/:provider Eliminar una clave API guardada para el proveedor especificado. HMAC + Auth
GET /api/provider-keys/:provider/resolve Descifrar y devolver la clave API completa para el proveedor especificado. Auth
GET /api/provider-keys/mode Obtener el modo de clave actual (proporcionada por el usuario vs. creditos de plataforma) y el saldo de creditos restante. Auth

Proveedores Permitidos

El parametro de ruta :provider debe ser uno de los siguientes valores:

Endpoints de Uso

Rastrear uso, consultar analiticas, monitorear gastos y gestionar presupuestos.

Metodo Endpoint Descripcion Auth
POST /api/usage/ingest Ingerir un registro de datos de uso (por ejemplo, conteos de tokens, modelo utilizado). Auth
GET /api/usage/query Consultar analiticas de uso con filtros flexibles (rango de fechas, modelo, agente). Auth
GET /api/usage/summary Obtener un resumen de uso para un periodo dado. Pase period como parametro de consulta (por ejemplo, day, week, month). Auth
GET /api/usage/analytics Recuperar analiticas de uso detalladas incluyendo desgloses por modelo y agente. Auth
GET /api/usage/spending Obtener datos de gasto para un periodo dado. Pase period como parametro de consulta. Auth
GET /api/usage/budget Obtener informacion de presupuesto incluyendo el limite total, monto utilizado y monto restante. Auth
POST /api/usage/cron-runs Registrar la ejecucion de un trabajo programado (cron) para seguimiento de uso. Auth
POST /api/usage/budget-snapshot Capturar una instantanea puntual del estado actual del presupuesto. Auth

Endpoints de Onboarding

Guiar a nuevos usuarios a traves de la configuracion inicial, incluyendo la seleccion de un proveedor de modelos y la configuracion de una clave API.

Metodo Endpoint Descripcion Auth
POST /api/onboarding/init Inicializar la configuracion de onboarding para el usuario autenticado. Crea ajustes predeterminados y devuelve el estado de onboarding. JWT
GET /api/onboarding/models Listar proveedores de modelos disponibles y sus modelos soportados. Este endpoint es publico y no requiere autenticacion. Ninguna
POST /api/onboarding/setup Configurar una clave API de proveedor durante el onboarding. Valida la clave antes de guardar. Tenant + Admin
POST /api/onboarding/complete Marcar el onboarding como completo para el usuario actual. Dashboard Auth

Endpoints de Inquilinos

Crear y gestionar inquilinos (espacios de trabajo), almacenar secretos cifrados y crear sesiones y trabajos directamente.

Metodo Endpoint Descripcion Auth
POST /api/tenants/ Crear un nuevo inquilino (espacio de trabajo). Devuelve el ID del inquilino y ajustes predeterminados. JWT
GET /api/tenants/:tenantId Obtener detalles para un inquilino especifico, incluyendo ajustes y conteo de miembros. JWT
POST /api/tenants/secrets Almacenar un secreto cifrado asociado con el inquilino. Usado para integraciones de servicios. Tenant + Admin
POST /api/tenants/sessions Crear una nueva sesion dentro del inquilino. Tenant + Admin
POST /api/tenants/jobs Crear un nuevo trabajo asincrono dentro del inquilino. Tenant + Admin

Endpoints de Memoria

Gestionar configuracion de memoria del agente, archivos y contenido. La memoria permite a los agentes persistir informacion entre sesiones.

Metodo Endpoint Descripcion Auth
GET /api/memory/config Obtener la configuracion actual de memoria (estado habilitado, politica de retencion, limites). Auth
POST /api/memory/config Actualizar ajustes de memoria como periodo de retencion y limites de almacenamiento. Auth
GET /api/memory/files Listar todos los archivos de memoria almacenados para el agente. Auth
GET /api/memory/files/:filename Recuperar el contenido de un archivo de memoria especifico por nombre de archivo. Auth
DELETE /api/memory/files/:filename Eliminar un archivo de memoria especifico por nombre de archivo. Auth
GET /api/memory/content Recuperar contenido de memoria almacenado. Auth
POST /api/memory/content Almacenar nuevo contenido de memoria para el agente. Auth

Endpoints de Cuentas de Google

Gestionar cuentas de Google que han sido conectadas a Neotask via OAuth.

Metodo Endpoint Descripcion Auth
GET /api/google-accounts/ Listar todas las cuentas de Google conectadas con sus alcances de servicio y estado. Auth
POST /api/google-accounts/:accountId/activate Activar una cuenta de Google conectada, habilitando al agente para usar sus servicios autorizados. Auth
DELETE /api/google-accounts/:accountId Eliminar una cuenta de Google conectada y revocar sus tokens almacenados. Auth

Endpoints de Contacto y Soporte

Enviar y gestionar solicitudes de contacto de soporte.

Metodo Endpoint Descripcion Auth
POST /api/contact/ Enviar un mensaje del formulario de contacto. Limitado a 5 solicitudes por 15 minutos por direccion IP. Ninguna
GET /api/contacts/ Listar todos los envios de contacto con soporte de paginacion. Solo admin. Admin
PATCH /api/contacts/:id Actualizar el estado de un envio de contacto (por ejemplo, marcar como resuelto). Admin
DELETE /api/contacts/:id Eliminar un envio de contacto. Admin

Limites de Tasa

Neotask aplica limites de tasa en ciertos endpoints para proteger la estabilidad del servicio. Cuando se excede un limite de tasa, la API devuelve una respuesta 429 Too Many Requests.

Categoria de Endpoint Limite
Formulario de contacto 5 solicitudes por 15 minutos por IP
Intentos de inicio de sesion 10 solicitudes por 15 minutos por IP
Seguimiento/analitica 30 solicitudes por 60 segundos por IP

Respuestas de Error

Todas las respuestas de error siguen un formato JSON consistente:

{
  "error": "Descripcion del mensaje de error",
  "status": 400
}

Codigos de Estado

Codigo Significado
400 Solicitud Incorrecta -- La solicitud estaba mal formada o contenia parametros invalidos.
401 No Autorizado -- Falta la autenticacion o el token proporcionado es invalido.
402 Pago Requerido -- Los creditos del inquilino se han agotado. Actualice su plan o agregue creditos para continuar.
403 Prohibido -- El usuario autenticado no tiene permisos suficientes para esta accion.
404 No Encontrado -- El recurso solicitado no existe.
429 Limite de Tasa Excedido -- Demasiadas solicitudes. Espere y reintente despues del periodo indicado en los encabezados de respuesta.
500 Error Interno del Servidor -- Ocurrio un error inesperado en el servidor. Si persiste, contacte al soporte de Neotask.