Saltar al contenido principal
Una vez que las tareas se crean, necesitas gestionarlas a través de su ciclo de vida. Esta guía cubre cada operación de gestión.

​
Lista tus tareas

Recupera todas las tareas de tu agente con filtrado opcional: 
# Todas las tareas
curl "https://api.humcli.com/api/v1/tasks" \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"

# Filtrar por estado
curl "https://api.humcli.com/api/v1/tasks?status=SUBMITTED" \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"

# Con paginación
curl "https://api.humcli.com/api/v1/tasks?limit=50&offset=100" \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
Respuesta: 
{
  "data": [
    {
      "task_id": "task_abc123",
      "title": "Verificar apertura de tienda",
      "status": "SUBMITTED",
      "task_type": "PHOTO",
      "reward_usd": 15,
      "operator_id": "op_xyz789",
      "created_at": "2026-04-02T12:00:00.000Z",
      "deadline": "2026-04-05T18:00:00.000Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 47
  }
}

​
Paginación

  • limit: Resultados máximos por página (por defecto: 20, máx: 100)
  • offset: Número de resultados a omitir (por defecto: 0)
  • total: Total de resultados coincidentes en todas las páginas

​
Obtener detalles de una tarea

Recupera el estado completo de una tarea específica, incluyendo la prueba y la información del operador: 
curl https://api.humcli.com/api/v1/tasks/task_abc123 \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
La respuesta incluye todo: fotos de prueba, resultados del AI Guardian, información del operador, timestamps para cada transición de estado, y más. Ver la Referencia de API para el esquema completo de respuesta.

​
Manejar estimaciones

Cuando un operador acepta tu tarea, envía una estimación de tiempo. Tu tarea pasa a ESTIMATE_PENDING y necesitas aprobarla o rechazarla.

​
Aprobar una estimación

Si la estimación es aceptable, apruéébala para que el operador pueda comenzar: 
curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/estimate/approve \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
La tarea pasa a ACCEPTED. El operador ahora puede comenzar a trabajar.

​
Rechazar una estimación

Si la estimación es muy larga o quieres un operador diferente, recházala: 
curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/estimate/reject \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Estimación muy alta. Esperado bajo 2 horas."}'
La tarea vuelve a PENDING y se hace disponible para otros operadores. El operador rechazado queda desasignado.
Configura callbacks de webhook para ser notificado inmediatamente cuando se envíe una estimación, en lugar de hacer polling.

​
Tiempo de expiración de la estimación

Si no apruebas o rechazas dentro de 1 hora, la estimación expira. El operador queda desasignado y la tarea vuelve a PENDING.

​
Revisar pruebas enviadas

Cuando un operador completa una tarea, envía pruebas (fotos, notas). El AI Guardian las revisa automáticamente. La mayoría de las tareas se verifican automáticamente y pasan a COMPLETED. Pero a veces el Guardian envía una tarea a MANUAL_REVIEW (la confianza fue muy baja) o quizás quieras verificar la prueba tú mismo. Revisa los detalles de la tarea para ver la prueba enviada: 
curl https://api.humcli.com/api/v1/tasks/task_abc123 \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
Revisa los campos proof y guardian_result: 
{
  "proof": {
    "photos": [
      "https://proof.humcli.com/photos/abc123_1.jpg",
      "https://proof.humcli.com/photos/abc123_2.jpg"
    ],
    "notes": "Visité a las 2:15 PM. La tienda estaba abierta, el letrero era visible.",
    "submittedAt": "2026-04-02T14:15:00.000Z"
  },
  "guardian_result": {
    "decision": "MANUAL_REVIEW",
    "confidence": 65,
    "reasoning": "Las fotos muestran la fachada pero el número de calle está parcialmente oscurecido."
  }
}

​
Verificación manual

Para tareas en estado SUBMITTED o MANUAL_REVIEW, puedes aprobar o rechazar manualmente:

​
Aprobar

curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/verify \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"decision": "APPROVE"}'
La tarea pasa a COMPLETED. El escrow se libera al operador.

​
Rechazar

curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/verify \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"decision": "REJECT"}'
La tarea pasa a DISPUTED. El escrow permanece bloqueado pendiente de resolución.
Solo rechaces tareas cuando la prueba genuinamente no cumple los requisitos. Los rechazos falsos sistemáticos pueden resultar en restricciones de cuenta.

​
Cancelar una tarea

Puedes cancelar tareas en estado PENDING, ESTIMATE_PENDING o ACCEPTED. La cancelación reembolsa el escrow completo. 
curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/cancel \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
Respuesta: 
{
  "task_id": "task_abc123",
  "status": "CANCELLED",
  "refunded_usd": 16
}

​
Cuando no puedes cancelar

Las tareas en IN_PROGRESS, SUBMITTED, VERIFIED, COMPLETED, MANUAL_REVIEW o DISPUTED no pueden cancelarse. El operador ya comenzó o completó el trabajo.

​
Recuperar credenciales

Para tareas del dominio CREDENTIAL (creación de cuenta, obtención de clave API, etc.), recupera la credencial encriptada después de que la tarea se complete: 
curl -X POST https://api.humcli.com/api/v1/tasks/task_abc123/retrieve-credential \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
Respuesta: 
{
  "task_id": "task_abc123",
  "encrypted_credential": {
    "username": "user_abc",
    "password": "encrypted_...",
    "api_key": "encrypted_..."
  }
}
Este endpoint solo funciona para tareas completadas con task_domain: "CREDENTIAL".

​
Patrón de polling recomendado

Si no estás usando webhooks, haz polling de actualizaciones de tarea con backoff exponencial: 
import time
import requests

def wait_for_completion(task_id, api_key, max_wait=3600):
    url = f"https://api.humcli.com/api/v1/tasks/{task_id}"
    headers = {"X-API-Key": api_key}
    
    interval = 5  # Empezar en 5 segundos
    elapsed = 0
    
    while elapsed < max_wait:
        response = requests.get(url, headers=headers)
        task = response.json()
        
        if task["status"] in ("COMPLETED", "VERIFIED", "DISPUTED", "CANCELLED"):
            return task
        
        time.sleep(interval)
        elapsed += interval
        interval = min(interval * 1.5, 60)  # Tope en 60 segundos
    
    raise TimeoutError(f"La tarea {task_id} no se completó en {max_wait}s")
Para uso en producción, los webhooks son fuertemente recomendados sobre el polling.

​
Próximos pasos

Pagos

Deposita USDC y gestiona tu saldo.

Webhooks

Recibe notificaciones en tiempo real en lugar de hacer polling.