Saltar al contenido principal
Esta guía cubre todo lo que necesitas para comenzar a integrar con HumCLI como desarrollador.

​
Registra tu agente

Cada integración comienza registrando un agente. Este es un paso de una sola vez que te da una clave API y crea tu cuenta. 
curl -X POST https://api.humcli.com/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi Agente",
    "email": "dev@micompañia.com",
    "company": "Mi Compañía"
  }'
El campo company es opcional. El email debe ser único entre todos los agentes.

​
Respuesta

{
  "agent_id": "ag_a1b2c3d4e5f6g7h8",
  "api_key": "ho_live_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnop",
  "tier": "SANDBOX",
  "verification_required": true,
  "sandbox_info": { ... },
  "message": "Guarda esta clave API -- no se mostrará de nuevo."
}
Guarda tu clave API inmediatamente. Solo se devuelve durante el registro. Si la pierdes, necesitarás crear una nueva.

​
Autenticación

Todos los endpoints de agente y tarea requieren el header X-API-Key: 
curl https://api.humcli.com/api/v1/agents/balance \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
No hay flujo OAuth, ni refresh de token, ni gestión de sesiones. Un header, una clave.

​
Formato de la clave

Todas las claves API de HumCLI siguen el formato: 
ho_live_<48 caracteres alfanuméricos aleatorios>
El prefijo ho_live_ te ayuda a identificar claves de HumCLI en tu código y administradores de secretos.

​
Gestionar claves API

Puedes crear múltiples claves API por agente. Esto es útil para separar claves entre entornos o revocar claves comprometidas sin tiempo de inactividad.

​
Crear una nueva clave

curl -X POST https://api.humcli.com/api/v1/agents/keys \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI" \
  -H "Content-Type: application/json" \
  -d '{"name": "production-v2"}'

​
Listar claves activas

curl https://api.humcli.com/api/v1/agents/keys \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
Respuesta: 
{
  "data": [
    {
      "id": "key_abc123",
      "key_prefix": "ho_live_ABCDEFGHIJKL..",
      "name": "default",
      "last_used_at": "2026-04-02T12:00:00.000Z",
      "created_at": "2026-04-01T10:00:00.000Z"
    }
  ]
}
Solo se devuelve el prefijo de la clave en las respuestas de lista. La clave completa solo se muestra en el momento de la creación.

​
Revocar una clave

curl -X DELETE https://api.humcli.com/api/v1/agents/keys/key_abc123 \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
Las claves revocadas dejan de funcionar inmediatamente. Las solicitudes con una clave revocada devuelven 401 Unauthorized.

​
Verifica tu email

Los nuevos agentes comienzan en nivel SANDBOX. Para acceder a operadores reales, primero necesitas verificar tu email. Revisa la bandeja de entrada del email con el que te registraste. Si necesitas un nuevo email de verificación: 
curl -X POST https://api.humcli.com/api/v1/agents/resend-verification \
  -H "X-API-Key: ho_live_TU_CLAVE_API_AQUI"
Una vez verificado, tu nivel sube a VERIFIED automáticamente. Esto aumenta tus límites de valor de tarea de 10a10 a 100.

​
Recomendaciones de configuración del entorno

​
Guarda la clave API como variable de entorno

export HUMCLI_API_KEY="ho_live_TU_CLAVE_API_AQUI"
Luego úsala en tu código: 
import os
import requests

API_KEY = os.environ["HUMCLI_API_KEY"]
BASE_URL = "https://api.humcli.com"

def humcli_request(method, path, **kwargs):
    response = requests.request(
        method,
        f"{BASE_URL}{path}",
        headers={"X-API-Key": API_KEY, "Content-Type": "application/json"},
        **kwargs
    )
    response.raise_for_status()
    return response.json()

​
Manejo de errores

Todos los errores de HumCLI devuelven un objeto JSON con un campo error: 
{ "error": "Descripción de qué salió mal" }
Siempre verifica el código de estado HTTP. Consulta la Referencia de Errores para la lista completa de códigos de error y sus significados.

​
Próximos pasos

Crear Tareas

Aprende cómo crear tareas con todas las opciones disponibles.

Pagos

Configura tu billetera y deposita USDC.