# Human//Error

> Human//Error turns your AI agents into a living city: every agent a building, every message a courier on a rail, and every risky action held at a gate until a human approves it. It is in early access, by email.

## Signing up for your human (AI agents)

AI agents may sign up on behalf of their human. Use this path instead of the web form: the web form has a
human check (Cloudflare Turnstile) and is for people. Every signup is recorded as either a human or an
agent signup, so please use this path and name yourself honestly.

Your human still proves the address: we email them an 8-digit code, and you need that code to finish.
Only sign up an address whose owner asked you to.

### 1. Request a code

`POST https://humanerror.si/api/agent/signup` with a JSON body:

- `email` (required): your human's email address
- `agent_name` (required): your name, 1-64 characters: letters, digits, spaces and `. _ ( ) ' & + -`. It appears in the email to your human, so no links, domains or email addresses (use `agent_url` for a link).
- `agent_url` (optional): an http(s) URL about you or your maker, up to 200 characters
- `on_behalf_of` (optional): your human's name, up to 64 characters

```sh
curl -sS https://humanerror.si/api/agent/signup \
  -H 'Content-Type: application/json' \
  -d '{"email":"human@example.com","agent_name":"Otto","agent_url":"https://example.com/otto","on_behalf_of":"Ada"}'
```

Response: `200 {"ok":true,"next":"code","message":"...","verify":{...}}`. We email an 8-digit code to the
address. Ask your human to read it to you. The code expires after an hour, and a new code can be requested
once a minute.

### 2. Send the code

`POST https://humanerror.si/api/agent/verify` with `{"email", "code"}`:

```sh
curl -sS https://humanerror.si/api/agent/verify \
  -H 'Content-Type: application/json' \
  -d '{"email":"human@example.com","code":"12345678"}'
```

Response: `200 {"ok":true,"token":"...","message":"Signed up. ..."}`. Your human is on the list.

### 3. Optional: choose a starting path

With the `token` from step 2 (valid for an hour) you can answer three optional questions for your human:

```sh
curl -sS https://humanerror.si/api/answers \
  -H 'Content-Type: application/json' \
  -d '{"token":"<token>","answers":{"built":"code","tools":["github","vercel"],"billing":"own_keys"}}'
```

- `built`: `never` | `builder` (a site builder like Squarespace, Wix or Webflow) | `code` (wrote the code and put it online)
- `tools`: any of `stripe`, `vercel`, `cloudflare`, `supabase`, `ai_keys` (OpenAI or Anthropic API keys), `github`, or `["none"]`
- `billing`: `one_bill` (one bill from Human//Error) | `own_keys` (their own accounts and API keys) | `unsure`

Response: `200 {"ok":true,"segment":"beginner"|"pro"}`.

## Errors

JSON with `{"ok":false,"error":"..."}`:

- `400 invalid_email`, `invalid_agent_name`, `invalid_agent_url`, `invalid_on_behalf_of` (with a `message`)
- `400 invalid_code`: the code is wrong or has expired; ask your human for the newest one
- `429 rate_limited`: wait for the number of seconds in `Retry-After` (60)

The agent endpoints allow a few requests per minute per IP address. Bodies are JSON, at most 4 KB.

## More

- Human-readable version of this page: https://humanerror.si/agents
- The site: https://humanerror.si/