aiworker/docs/02-backend/api-endpoints.md

API Endpoints

Base URL

http://localhost:3000/api

Authentication

Todos los endpoints (excepto /health) requieren autenticación JWT:

Authorization: Bearer <token>

---

Projects

GET /projects

Lista todos los proyectos.

Response:

{
  "projects": [
    {
      "id": "uuid",
      "name": "My Project",
      "description": "Project description",
      "giteaRepoUrl": "http://gitea/owner/repo",
      "k8sNamespace": "my-project",
      "status": "active",
      "createdAt": "2026-01-19T10:00:00Z"
    }
  ]
}

GET /projects/:id

Obtiene detalles de un proyecto.

POST /projects

Crea un nuevo proyecto.

Body:

{
  "name": "My New Project",
  "description": "Project description",
  "dockerImage": "node:20-alpine",
  "envVars": {
    "NODE_ENV": "production"
  },
  "replicas": 2,
  "cpuLimit": "1000m",
  "memoryLimit": "1Gi"
}

Response:

{
  "project": {
    "id": "uuid",
    "name": "My New Project",
    "giteaRepoUrl": "http://gitea/owner/my-new-project",
    "k8sNamespace": "my-new-project-abc123"
  }
}

PATCH /projects/:id

Actualiza un proyecto.

DELETE /projects/:id

Elimina un proyecto y todos sus recursos.

---

Tasks

GET /tasks

Lista tareas con filtros opcionales.

Query params:

• projectId: Filtrar por proyecto
• state: Filtrar por estado (backlog, in_progress, etc.)
• assignedAgentId: Filtrar por agente
• limit: Límite de resultados (default: 50)
• offset: Offset para paginación

Response:

{
  "tasks": [
    {
      "id": "uuid",
      "projectId": "uuid",
      "title": "Implement login",
      "description": "Create authentication system",
      "state": "in_progress",
      "priority": "high",
      "assignedAgentId": "agent-123",
      "branchName": "task-abc-implement-login",
      "prNumber": 42,
      "prUrl": "http://gitea/owner/repo/pulls/42",
      "previewUrl": "https://task-abc.preview.aiworker.dev",
      "createdAt": "2026-01-19T10:00:00Z"
    }
  ],
  "total": 10,
  "limit": 50,
  "offset": 0
}

GET /tasks/:id

Obtiene detalles completos de una tarea incluyendo preguntas.

Response:

{
  "task": {
    "id": "uuid",
    "title": "Implement login",
    "state": "needs_input",
    "questions": [
      {
        "id": "q-uuid",
        "question": "Which auth library should I use?",
        "context": "Need to choose between JWT or session-based",
        "askedAt": "2026-01-19T11:00:00Z",
        "status": "pending"
      }
    ],
    "project": {
      "name": "My Project",
      "giteaRepoUrl": "..."
    }
  }
}

POST /tasks

Crea una nueva tarea.

Body:

{
  "projectId": "uuid",
  "title": "Implement feature X",
  "description": "Detailed description...",
  "priority": "high"
}

PATCH /tasks/:id

Actualiza una tarea.

Body:

{
  "state": "approved",
  "notes": "Looks good!"
}

POST /tasks/:id/respond

Responde a una pregunta del agente.

Body:

{
  "questionId": "q-uuid",
  "response": "Use JWT with jsonwebtoken library"
}

Response:

{
  "success": true,
  "question": {
    "id": "q-uuid",
    "status": "answered",
    "respondedAt": "2026-01-19T11:05:00Z"
  }
}

POST /tasks/:id/approve

Aprueba una tarea en estado ready_to_test.

POST /tasks/:id/reject

Rechaza una tarea y la regresa a in_progress.

Body:

{
  "reason": "Needs more tests"
}

---

Task Groups (Merges)

POST /task-groups

Crea un grupo de tareas para merge a staging/production.

Body:

{
  "projectId": "uuid",
  "taskIds": ["task-1", "task-2", "task-3"],
  "targetBranch": "staging",
  "notes": "Sprint 1 features"
}

Response:

{
  "taskGroup": {
    "id": "uuid",
    "taskIds": ["task-1", "task-2", "task-3"],
    "status": "pending",
    "stagingBranch": "release/sprint-1"
  }
}

GET /task-groups/:id

Obtiene detalles de un task group.

POST /task-groups/:id/deploy-staging

Despliega el task group a staging.

POST /task-groups/:id/deploy-production

Despliega el task group a production.

---

Agents

GET /agents

Lista todos los agentes.

Response:

{
  "agents": [
    {
      "id": "agent-123",
      "podName": "claude-agent-abc123",
      "status": "busy",
      "currentTaskId": "task-uuid",
      "capabilities": ["javascript", "react", "node"],
      "tasksCompleted": 42,
      "lastHeartbeat": "2026-01-19T12:00:00Z"
    }
  ]
}

GET /agents/:id

Obtiene detalles de un agente incluyendo logs recientes.

GET /agents/:id/logs

Obtiene logs del agente.

Query params:

• limit: Número de logs (default: 100)
• level: Filtrar por nivel (debug, info, warn, error)

---

Deployments

GET /deployments

Lista deployments con filtros.

Query params:

• projectId: Filtrar por proyecto
• environment: Filtrar por entorno
• status: Filtrar por estado

GET /deployments/:id

Obtiene detalles de un deployment.

POST /deployments/:id/rollback

Hace rollback de un deployment.

Response:

{
  "success": true,
  "rollbackDeploymentId": "new-uuid"
}

---

Health & Status

GET /health

Health check del backend.

Response:

{
  "status": "ok",
  "timestamp": "2026-01-19T12:00:00Z",
  "services": {
    "mysql": "connected",
    "redis": "connected",
    "gitea": "reachable",
    "kubernetes": "connected"
  },
  "version": "1.0.0"
}

GET /metrics

Métricas del sistema (Prometheus format).

---

WebSocket Events

Conectar a: ws://localhost:3000

Client → Server

{
  "event": "auth",
  "data": {
    "token": "jwt-token"
  }
}

{
  "event": "subscribe",
  "data": {
    "projectId": "uuid"
  }
}

Server → Client

{
  "event": "task:created",
  "data": {
    "taskId": "uuid",
    "projectId": "uuid",
    "title": "New task"
  }
}

{
  "event": "task:status_changed",
  "data": {
    "taskId": "uuid",
    "oldState": "in_progress",
    "newState": "ready_to_test",
    "previewUrl": "https://..."
  }
}

{
  "event": "task:needs_input",
  "data": {
    "taskId": "uuid",
    "questionId": "q-uuid",
    "question": "Which library?"
  }
}

{
  "event": "agent:status",
  "data": {
    "agentId": "agent-123",
    "status": "idle",
    "lastTaskId": "task-uuid"
  }
}

{
  "event": "deploy:started",
  "data": {
    "deploymentId": "uuid",
    "environment": "staging"
  }
}

{
  "event": "deploy:completed",
  "data": {
    "deploymentId": "uuid",
    "environment": "staging",
    "url": "https://staging-project.aiworker.dev"
  }
}

---

Error Responses

Todos los endpoints pueden retornar estos errores:

400 Bad Request

{
  "error": "Validation error",
  "details": {
    "field": "projectId",
    "message": "Required"
  }
}

401 Unauthorized

{
  "error": "Invalid or expired token"
}

404 Not Found

{
  "error": "Resource not found"
}

500 Internal Server Error

{
  "error": "Internal server error",
  "requestId": "req-uuid"
}