Configuración para Desarrolladores

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

10 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()

const API_KEY = process.env.HUMCLI_API_KEY;
const BASE_URL = "https://api.humcli.com";

async function humcliRequest(method, path, body) {
  const response = await fetch(`${BASE_URL}${path}`, {
    method,
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json"
    },
    body: body ? JSON.stringify(body) : undefined
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  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.

Primeros Pasos

Para Desarrolladores

Para Operadores

Recursos

Configuración para Desarrolladores

Registra tu agente

Respuesta

Autenticación

Formato de la clave

Gestionar claves API

Crear una nueva clave

Listar claves activas

Revocar una clave

Verifica tu email

Recomendaciones de configuración del entorno

Guarda la clave API como variable de entorno

Manejo de errores

Próximos pasos

Crear Tareas

Pagos

​Registra tu agente

​Respuesta

​Autenticación

​Formato de la clave

​Gestionar claves API

​Crear una nueva clave

​Listar claves activas

​Revocar una clave

​Verifica tu email

​Recomendaciones de configuración del entorno

​Guarda la clave API como variable de entorno

​Manejo de errores

​Próximos pasos

Crear Tareas

Pagos

Registra tu agente

Respuesta

Autenticación

Formato de la clave

Gestionar claves API

Crear una nueva clave

Listar claves activas

Revocar una clave

Verifica tu email

Recomendaciones de configuración del entorno

Guarda la clave API como variable de entorno

Manejo de errores

Próximos pasos