Documentación de API

Referencia técnica para la API REST de Resolflow e integración WebSocket

Referencia de API interna

Esta documentación describe la API REST interna de Resolflow para entender cómo funciona la plataforma. Resolflow es una aplicación autónoma, no una API de plataforma para integraciones de terceros. Si necesitas interactuar con Resolflow mediante programación, usa el protocolo MCP en su lugar.

Resumen de la API

Arquitectura y capacidades

Diseño RESTful

Métodos HTTP estándar (GET, POST, PATCH, DELETE)

Actualizaciones en tiempo real

WebSocket para notificaciones en vivo

Respuestas JSON

Formato de datos consistente

Autenticación

Autenticación basada en JWT con tokens duales

Sistema de tokens

Token de acceso
15 minutos

Token de corta duración almacenado en cookie HTTP-only. Usado para solicitudes de API.

Token de actualización
7 días

Token de larga duración para obtener nuevos tokens de acceso sin volver a iniciar sesión.

# Inicia sesión para obtener tokens

POST /api/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "yourpassword"
}

Response:
{
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe"
  },
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}

# Usa el token de acceso en las solicitudes

GET /api/workspaces
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Endpoints principales de la API

Recursos y operaciones principales

Autenticación

POST
/api/auth/register

Crear nueva cuenta

POST
/api/auth/login

Iniciar sesión con email/contraseña

POST
/api/auth/refresh

Obtener nuevo token de acceso

POST
/api/auth/logout

Borrar tokens y finalizar sesión

GET
/api/auth/me

Obtener info del usuario actual

Espacios de trabajo

GET
/api/workspaces

Listar todos los espacios de trabajo

GET
/api/workspaces/:id

Obtener detalles del espacio de trabajo

POST
/api/workspaces

Crear nuevo espacio de trabajo

PATCH
/api/workspaces/:id

Actualizar espacio de trabajo

DELETE
/api/workspaces/:id

Eliminar espacio de trabajo

Proyectos

GET
/api/workspaces/:workspaceId/projects

Listar proyectos en el espacio de trabajo

POST
/api/workspaces/:workspaceId/projects

Crear proyecto

PATCH
/api/projects/:id

Actualizar configuración del proyecto

Tareas y Todos

GET
/api/projects/:projectId/tasks

Listar tareas

POST
/api/projects/:projectId/tasks

Crear tarea

GET
/api/tasks/:taskId/todos

Listar todos de una tarea

PATCH
/api/todos/:id

Actualizar estado del todo

Agentes y Conexiones

GET
/api/workspaces/:workspaceId/agents

Listar agentes MCP

POST
/api/projects/:projectId/tokens

Generar token MCP

GET
/api/workspaces/:workspaceId/repos

Listar repos de GitHub conectados

Orquestador

POST
/api/orchestrator/suggest-tasks

Generación de tareas con IA

GET
/api/orchestrator/inbox

Obtener mensajes del orquestador

POST
/api/orchestrator/ask

Pedir orientación al orquestador

Informes y Análisis

GET
/api/projects/:projectId/reports

Listar informes

GET
/api/reports/:id

Obtener detalles del informe

Actualizaciones en tiempo real WebSocket

Notificaciones en vivo y sincronización de datos

Conéctate al servidor WebSocket para actualizaciones en tiempo real de tareas, todos, mensajes del orquestador e informes.

# Conectar al WebSocket

// Send authentication
{
  "type": "auth",
  "token": "your-access-token"
}

// Subscribe to workspace updates
{
  "type": "subscribe",
  "workspaceId": "workspace-uuid"
}

// Receive updates
{
  "type": "task_updated",
  "data": {
    "taskId": "uuid",
    "status": "in_progress",
    "updatedBy": "agent-name"
  }
}

Tipos de eventos

task_created

Nueva tarea añadida

task_updated

Estado de tarea cambiado

todo_updated

Actualización de progreso del todo

orchestrator_message

Nueva orientación de la IA

report_generated

Nuevo informe de análisis

loop_signal

Agente atascado detectado

Ejemplo: Crear tarea

Flujo completo de solicitud y respuesta

Solicitud

POST /api/projects/550e8400-e29b-41d4-a716-446655440000/tasks
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

{
  "title": "Add dark mode support",
  "description": "Implement dark mode toggle with system preference detection",
  "type": "feature",
  "priority": "medium"
}

Respuesta (201 Created)

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "title": "Add dark mode support",
  "description": "Implement dark mode toggle with system preference detection",
  "type": "feature",
  "priority": "medium",
  "status": "not_started",
  "projectId": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "user-uuid",
  "createdAt": "2024-02-12T10:30:00Z",
  "updatedAt": "2024-02-12T10:30:00Z"
}

Límites de tasa y Mejores prácticas

Directrices para el uso de la API

Límites de tasa

Actualmente no se aplican límites de tasa para instancias autoalojadas. Para despliegues en producción, considera implementar limitación de tasa según tu infraestructura.

Mejores prácticas

  • • Usa WebSocket para datos en tiempo real en lugar de polling
  • • Almacena en caché las respuestas del lado del cliente (React Query lo gestiona)
  • • Agrupa operaciones cuando sea posible (creación masiva de todos)
  • • Gestiona la actualización de tokens automáticamente con interceptores
  • • Usa actualizaciones optimistas para mejor UX

Manejo de errores

Códigos de estado HTTP estándar:

  • • 200 - Éxito
  • • 201 - Creado
  • • 400 - Solicitud incorrecta (errores de validación)
  • • 401 - No autorizado (token inválido/expirado)
  • • 403 - Prohibido (permisos insuficientes)
  • • 404 - No encontrado
  • • 500 - Error del servidor