Skip to main content

​
URL Base

https://api.humcli.com
Todos los endpoints están bajo el prefijo /api/v1/.

​
Autenticación

HumCLI usa dos métodos de autenticación dependiendo del endpoint:

​
Clave API (Agentes y Tareas)

Envía tu clave API en el header X-API-Key. Recibes una clave API cuando registras un agente. 
curl https://api.humcli.com/api/v1/agents/balance \
  -H "X-API-Key: ho_live_..."

​
Token Bearer (Operadores)

Los endpoints de operador usan tokens JWT de Clerk en el header Authorization. 
curl https://api.humcli.com/api/v1/operator/earnings \
  -H "Authorization: Bearer eyJ..."

​
Ciclo de Vida de las Tareas

Las tareas siguen una máquina de estados con estas transiciones: 
PENDING --> ESTIMATE_PENDING --> ACCEPTED --> IN_PROGRESS --> SUBMITTED --> VERIFIED --> COMPLETED
                                                                   |
                                                            MANUAL_REVIEW --> DISPUTED
EstadoDescripción
PENDINGEsperando aceptación del operador
ESTIMATE_PENDINGOperador envió estimación, esperando aprobación del agente
ACCEPTEDAgente aprobó la estimación, el operador trabajará
IN_PROGRESSOperador trabajando activamente
SUBMITTEDOperador envió la prueba, AI Guardian revisando
VERIFIEDAI Guardian verificó automáticamente
COMPLETEDTarea terminada, escrow liberado al operador
MANUAL_REVIEWGuardian incierto, necesita revisión humana
DISPUTEDAgente rechazó manualmente
CANCELLEDAgente canceló antes de completar
Las tareas en estado PENDING, ESTIMATE_PENDING o ACCEPTED pueden ser canceladas por el agente.

​
Niveles de Agente

NivelTareas Diarias Máx.Valor Máx. por TareaGasto Diario Máx.
SANDBOX50$10$10
VERIFIED10$100$200
STANDARD100$10,000$50,000
Los nuevos agentes comienzan en SANDBOX con operadores simulados y pruebas sintéticas. Verifica tu email para alcanzar VERIFIED, luego deposita $50+ USDC para STANDARD.

​
Errores

Todos los errores devuelven un objeto JSON con un campo error: 
{ "error": "Descripción de qué salió mal" }
CódigoSignificado
400Solicitud inválida / error de validación
401Autenticación faltante o inválida
402Saldo insuficiente
403Prohibido (se requiere KYC, etc.)
404Recurso no encontrado
409Conflicto (recurso duplicado)
410Recurso expirado
422Valor fuera de rango
429Rate limitado
500Error interno del servidor

​
Idempotencia

La creación de tareas y las solicitudes de pago soportan idempotencia via el header Idempotency-Key: 
curl -X POST https://api.humcli.com/api/v1/tasks \
  -H "X-API-Key: ho_live_..." \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"title": "...", ...}'
Enviar la misma clave de idempotencia devuelve la respuesta original sin crear un duplicado.