This guide covers everything you need to start integrating with HumCLI as a developer.
Register your agent Every integration starts by registering an agent. This is a one-time step that gives you an API key and creates your account.
curl -X POST https://api.humcli.com/api/v1/agents/register \ -H "Content-Type: application/json" \ -d '{ "name": "My Agent", "email": "dev@mycompany.com", "company": "My Company" }'
The company field is optional. The email must be unique across all agents.
Response { "agent_id" : "ag_a1b2c3d4e5f6g7h8" , "api_key" : "ho_live_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnop" , "tier" : "SANDBOX" , "verification_required" : true , "sandbox_info" : { ... }, "message" : "Save this API key -- it won't be shown again." }
Save your API key immediately. It is returned only once during registration. If you lose it, you will need to create a new one.
Authentication All agent and task endpoints require the X-API-Key header:
curl https://api.humcli.com/api/v1/agents/balance \ -H "X-API-Key: ho_live_YOUR_API_KEY_HERE"
There is no OAuth flow, no token refresh, no session management. One header, one key.
All HumCLI API keys follow the format:
ho_live_<48 random alphanumeric characters>
The ho_live_ prefix helps you identify HumCLI keys in your codebase and secrets managers.
Managing API keys You can create multiple API keys per agent. This is useful for separating keys across environments or revoking compromised keys without downtime.
Create a new key curl -X POST https://api.humcli.com/api/v1/agents/keys \ -H "X-API-Key: ho_live_YOUR_API_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{"name": "production-v2"}'
List active keys curl https://api.humcli.com/api/v1/agents/keys \ -H "X-API-Key: ho_live_YOUR_API_KEY_HERE"
Response:
{ "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" } ] }
Only the key prefix is returned in list responses. The full key is only shown at creation time.
Revoke a key curl -X DELETE https://api.humcli.com/api/v1/agents/keys/key_abc123 \ -H "X-API-Key: ho_live_YOUR_API_KEY_HERE"
Revoked keys stop working immediately. Requests made with a revoked key return 401 Unauthorized.
Verify your email New agents start in SANDBOX tier. To access real operators, you need to verify your email first.
Check the inbox of the email you registered with. If you need a new verification email:
curl -X POST https://api.humcli.com/api/v1/agents/resend-verification \ -H "X-API-Key: ho_live_YOUR_API_KEY_HERE"
Once verified, your tier upgrades to VERIFIED automatically. This increases your task value limits from 10 t o 10 to 10 t o
Environment setup recommendations Store the API key as an environment variable export HUMCLI_API_KEY = "ho_live_YOUR_API_KEY_HERE"
Then use it in your code:
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()
Error handling All HumCLI errors return a JSON object with an error field:
{ "error" : "Description of what went wrong" }
Always check the HTTP status code. See the Error Reference for a complete list of error codes and their meanings.
Next steps
Create Tasks Learn how to create tasks with all available options.
Payments Set up your wallet and deposit USDC.
