Developer Setup

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.

Key format

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 to

100.

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

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();
}

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.

Getting Started

For Developers

For Operators

Resources

Register your agent

Response

Authentication

Key format

Managing API keys

Create a new key

List active keys

Revoke a key

Verify your email

Environment setup recommendations

Store the API key as an environment variable

Error handling

Next steps

Create Tasks

Payments

​Register your agent

​Response

​Authentication

​Key format

​Managing API keys

​Create a new key

​List active keys

​Revoke a key

​Verify your email

​Environment setup recommendations

​Store the API key as an environment variable

​Error handling

​Next steps

Create Tasks

Payments

Register your agent

Response

Authentication

Key format

Managing API keys

Create a new key

List active keys

Revoke a key

Verify your email

Environment setup recommendations

Store the API key as an environment variable

Error handling

Next steps