> For the complete documentation index, see [llms.txt](https://docs.humblytics.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.humblytics.com/agent-onboarding-api.md).

# Agent Onboarding API

The Agent Onboarding API lets AI agents sign up users, start on a free plan, optionally buy the Agents plan, and receive an API key — all without the user opening a dashboard. This is designed for Claude Code, Cursor, and any agent that wants to onboard users programmatically.

> **Base URL**: `https://app.humblytics.com`

***

## Overview

Three ways for an agent to get a key, from most to least common:

1. [**Activate with an email**](#recommended-activate-with-an-email) (recommended) — the agent sends the person's email and site; the person clicks one **Activate** button in an email.
2. [**Link code**](#link-code-from-the-app) — the person is already signed in to Humblytics and pastes a prompt that carries a one-time `hbl_` code.
3. [**Allow screen**](#older-allow-screen-agent-initiate) (older) — `agent-initiate` returns a link the person opens to sign in and approve.

Every flow ends with an **account API key**: a 64-character hex string with no prefix. Use it with the MCP server (`https://mcp.humblytics.com/v1`, `Authorization: Bearer <apiKey>`) or the [External Analytics API](https://docs.humblytics.com/external-analytics-api.md). The key is delivered once; store it immediately.

***

## Recommended · Activate with an email

The default way for an agent with no Humblytics credentials to get a key. The agent sends the person's email and site plus a short proof of work. Humblytics emails the person one **Activate** button. That click creates the account (Free start: 5,000 data points, 1 site, no card) or uses the existing one (without signing the browser in), adds the site, attaches a homepage audit if one was sent, and releases an account API key to the agent's poll. There is no sign-in page and no email code.

### 1 · Get a challenge

`GET /api/v1/agent/activate/challenge`

| Query parameter | Required | Description                                     |
| --------------- | -------- | ----------------------------------------------- |
| `email`         | Yes      | The person's email                              |
| `url`           | Yes      | Their site, as a domain (`mysite.com`) or a URL |

```bash
curl "https://app.humblytics.com/api/v1/agent/activate/challenge?email=jane@example.com&url=mysite.com"
```

```json
{
  "nonce": "3f9c1e0a7b2d4c6e8f1a2b3c4d5e6f70",
  "timestamp": 1794950000000,
  "difficulty": 18,
  "signature": "9a1f…"
}
```

The challenge is bound to that email and site and is valid for 10 minutes. `400 invalid_email` or `400 invalid_url` when a parameter is unusable; `429 rate_limited` when asked too often.

### 2 · Solve the proof of work

Find a whole number `counter` (0, 1, 2, …) where SHA-256 of the text `<nonce>|<counter>` starts with `difficulty` zero bits. It takes a few seconds.

```javascript
const crypto = require("crypto");
const solve = (nonce, difficulty) => {
  for (let counter = 0; ; counter++) {
    const hash = crypto.createHash("sha256").update(`${nonce}|${counter}`).digest();
    let bits = 0;
    for (const byte of hash) {
      if (byte === 0) { bits += 8; continue; }
      bits += Math.clz32(byte) - 24;
      break;
    }
    if (bits >= difficulty) return counter;
  }
};
```

### 3 · Send the activation request

`POST /api/v1/agent/activate`

| Field                             | Required | Description                                                                                                                                                          |
| --------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`, `url`                    | Yes      | The same values the challenge was made for                                                                                                                           |
| `nonce`, `timestamp`, `signature` | Yes      | From the challenge, unchanged                                                                                                                                        |
| `counter`                         | Yes      | The solved counter (number or decimal string)                                                                                                                        |
| `agent_name`                      | No       | Your name as the person should see it, e.g. `Claude Code`                                                                                                            |
| `name`                            | No       | The person's name, used for a new account                                                                                                                            |
| `source`                          | No       | `agent` (default), `quick_start` or `audit`. Only `agent` activations receive an API key on the poll; the others are website starts and get `propertyId` and `site`. |
| `audit_token`                     | No       | An `hbt_` token from [Save a homepage audit](#save-a-homepage-audit); the audit and its drafted tests are saved to the site                                          |

```bash
curl -X POST https://app.humblytics.com/api/v1/agent/activate \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","url":"mysite.com","agent_name":"Claude Code","nonce":"3f9c…","timestamp":1794950000000,"signature":"9a1f…","counter":181234}'
```

```json
{
  "status": "ok",
  "poll_token": "hbp_…",
  "poll_url": "https://app.humblytics.com/api/v1/agent/activate/poll/hbp_…",
  "expires_at": "2026-11-18T21:00:00.000Z"
}
```

Every valid proof gets this same answer, whether the email is new, already has an account, or has hit its daily limit, so the response never reveals who has an account. Only a wrong, expired or reused proof answers `400 INVALID_PROOF_OF_WORK`: get a new challenge and solve it again.

### 4 · The person clicks Activate

Tell the person to check their inbox for the email from Humblytics and click **Activate**. Opening the link shows a confirm page; only the button activates, so email link scanners can't use it up. The link lasts 24 hours.

### 5 · Poll for the key

`GET <poll_url>` every 3 to 5 seconds.

```bash
curl https://app.humblytics.com/api/v1/agent/activate/poll/hbp_…
```

```json
{ "status": "pending" }
```

```json
{
  "status": "approved",
  "apiKey": "3f1c…64 hex characters…9e2a",
  "email": "jane@example.com",
  "propertyId": "c12c…",
  "site": "mysite.com"
}
```

`apiKey` is returned once, on the first `approved` answer; later polls answer `approved` without it. Collect it within **1 hour** of the click. `propertyId` is `null` (with `siteLimitReached: true`) when the account already has its 1 Free start site. `expired` means the link timed out or a newer request for the same email and site replaced it. Polling too fast answers `429 rate_limited`; back off and retry.

**Notes**

* The key is an account-level key with the same permissions as other agent keys. Launching a split test still needs the person's approval.
* Use the key with the MCP server `https://mcp.humblytics.com/v1` (`Authorization: Bearer <apiKey>`), then follow [agent.md](https://app.humblytics.com/agent.md) from Step 2.
* Limits: one live link per email and site (a new request replaces the old link), and daily caps per email and per IP. Nothing is created and no tracking runs until the click.
* The endpoint is also listed as `agent_activation_endpoint` in `https://app.humblytics.com/.well-known/oauth-authorization-server`.

### Save a homepage audit

`POST /api/v1/agent/audits`

If your agent audited the person's homepage before signing them up, save the audit first and pass the returned token as `audit_token` in the activation request. The audit and its drafted tests then appear on the site as soon as it is activated. No authentication is needed.

| Field     | Required | Description                                                                                                    |
| --------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| `url`     | Yes      | The audited page URL                                                                                           |
| `score`   | No       | 0–100                                                                                                          |
| `answers` | No       | `{ "action": [], "audience": [], "goal": [] }`, up to 3 short strings each                                     |
| `tests`   | Yes      | 1–3 drafted tests: `{ "title", "element", "before", "after", "why", "metric", "audience" }` (`title` required) |

```json
{ "audit_token": "hbt_…", "expires_at": "2026-11-19T20:00:00.000Z" }
```

Returns `201`. The token is valid for 24 hours; `400 invalid_audit` names the bad `field`.

***

## Link code from the app

When a person is already signed in, the Agents page (and the website audit) can hand their agent a prompt carrying a one-time code `hbl_…`. The agent's first call exchanges it for a key. No other authentication is needed: the code is the proof.

`POST /api/v1/auth/agent-link`

```bash
curl -X POST https://app.humblytics.com/api/v1/auth/agent-link \
  -H "Content-Type: application/json" \
  -d '{ "code": "hbl_…" }'
```

```json
{
  "apiKey": "3f1c…64 hex characters…9e2a",
  "email": "jane@example.com",
  "sites": [{ "propertyId": "c12c…", "domain": "mysite.com", "name": "mysite.com" }],
  "site": "mysite.com",
  "testId": null
}
```

`site` and `testId` name the site and drafted test the prompt came from, when it came from an audit. Codes last **15 minutes** and work once: `410 code_used`, `410 code_expired`, `400 code_invalid`, `429 rate_limited`.

***

## Older · Allow screen (`agent-initiate`)

Still supported for agents that read an older spec. The agent asks for an authorization link, the person opens it, signs in (or signs up by email code) and clicks **Approve access**; the agent polls for the key.

### Step 1 · Initiate

```bash
curl -X POST https://app.humblytics.com/api/v1/auth/agent-initiate \
  -H "Content-Type: application/json" \
  -d '{ "email": "user@example.com", "name": "Jane Smith" }'
```

| Name    | Type   | Required | Description                   |
| ------- | ------ | -------- | ----------------------------- |
| `email` | string | Yes      | User's email address          |
| `name`  | string | No       | Used if an account is created |

**Response (200)**

```json
{
  "status": "pending",
  "token": "<session-token>",
  "url": "https://app.humblytics.com/mcp-connect?token=<session-token>",
  "verifyUrl": "https://app.humblytics.com/mcp-connect?token=<session-token>",
  "pollUrl": "https://app.humblytics.com/api/mcp/poll/<session-token>",
  "expiresAt": 1234567890000
}
```

The answer is the same for every email, so it never reveals whether an account exists. `400 email_required` when `email` is missing. The link expires in **15 minutes**.

### Step 2 · User approval

Tell the user to open `url` in their browser. They sign in if needed (email code or Google — there is no password) and click **Approve access**. A new account starts on **Free start**: the first 5,000 data points are free, no card needed, with API and MCP access on.

{% hint style="warning" %}
The agent should present the URL clearly and wait for the user to complete the browser flow before proceeding.
{% endhint %}

### Step 3 · Poll for the key

Poll every 3–5 seconds until `status` is `"complete"`.

```bash
curl "https://app.humblytics.com/api/v1/auth/agent-signup-status?token=<session-token>"
```

```json
{ "status": "pending" }
```

```json
{ "status": "complete", "apiKey": "3f1c…64 hex characters…9e2a" }
```

| Status | Body                               | Meaning                               |
| ------ | ---------------------------------- | ------------------------------------- |
| 404    | `{ "error": "session_not_found" }` | Unknown or expired token — start over |
| 400    | `{ "error": "token_required" }`    | `token` is missing                    |

`pollUrl` from Step 1 answers the same way with `{ "status": "approved", "apiKey" }`.

{% hint style="warning" %}
The `apiKey` is delivered **once** — the session is deleted after this response. Store the key immediately.
{% endhint %}

***

## Using the key

All subsequent calls use the key as a Bearer header:

```http
Authorization: Bearer <apiKey>
```

It works with the MCP server and every endpoint of the [External Analytics API](https://docs.humblytics.com/external-analytics-api.md) and [Split Testing API](https://docs.humblytics.com/split-testing-api.md), including the account endpoints below.

### Check the account

```bash
curl -H "Authorization: Bearer <apiKey>" \
  https://app.humblytics.com/api/external/v1/account
```

Returns the plan, data-point balance and the account's sites. See [Account, Sites and Billing](https://docs.humblytics.com/external-analytics-api.md#account-sites-and-billing).

### Add a website

```bash
curl -X POST https://app.humblytics.com/api/external/v1/properties \
  -H "Authorization: Bearer <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{ "domain": "example.com", "name": "My Site" }'
```

The response carries the `propertyId`, `scriptId` and the ready-to-paste `snippet`:

```html
<script async src="https://app.humblytics.com/hmbl.min.js?id=<script-id>"></script>
```

`402 site_limit_reached` when the plan's site limit is reached (Free start includes 1 site; the Agents plan adds unlimited sites).

### Confirm the install

```bash
curl -H "Authorization: Bearer <apiKey>" \
  "https://app.humblytics.com/api/external/v1/properties/<propertyId>/install"
```

`status` moves from `not_installed` to `installed_waiting_for_first_pageview` to `live`. If the agent cannot add the script on the person's platform, report it with `POST /api/external/v1/properties/<propertyId>/setup-report` so the app tells the person what to paste.

***

## Removing a Website

If a website was added by mistake (for example a mistyped domain), the agent can call `DELETE /api/external/v1/properties/<propertyId>`, or the user can delete it from the Agents page at `/agent`:

1. Open `/agent` and find the site in the **Sites** list.
2. Click **Delete** on the site's row.
3. Type the site's domain to confirm, then click **Delete site**.

This is the same safeguard as **Site settings → Danger zone**. Deleting a site archives it and hides it from your dashboards. Historical data is kept, other sites are unaffected, adding the same domain again restores it, and support can restore it too.

{% hint style="info" %}
`GET /api/external/v1/account` and `GET /api/v2/properties` only list active sites, so an agent never has to filter archived ones.
{% endhint %}

The `/agent` page refreshes its site list when you switch back to the tab, so sites added or removed by your agent in another window appear without a manual reload.

***

## Agents Plan (Optional)

Payment is never required to finish signup. The account starts on **Free start** and can buy the **Agents plan** at any time:

| Plan        | Price        | Includes                                                                                                |
| ----------- | ------------ | ------------------------------------------------------------------------------------------------------- |
| Free start  | $0, no card  | First 5,000 data points, 1 site                                                                         |
| Agents plan | $39 one time | 100,000 data points for 12 months, unlimited sites. Not a subscription. Top up later at $29 per 100,000 |

An agent gets the checkout link with `POST /api/external/v1/billing/agents-checkout` and hands it to the person, who pays in a browser and returns to a confirmation page that applies the plan right away. Later top-ups (`POST /api/external/v1/billing/top-up`) charge the saved card. See [Account, Sites and Billing](https://docs.humblytics.com/external-analytics-api.md#account-sites-and-billing).

A data point is one tracked event; reads and tool calls are never counted. For more data points, features or higher limits, the user can move to Business or Scale in Account settings.

***

## Quick Reference

| Step                   | Method | Endpoint                                           |
| ---------------------- | ------ | -------------------------------------------------- |
| Activation challenge   | GET    | `/api/v1/agent/activate/challenge?email=&url=`     |
| Activate with an email | POST   | `/api/v1/agent/activate`                           |
| Poll for the key       | GET    | `/api/v1/agent/activate/poll/<poll_token>`         |
| Save a homepage audit  | POST   | `/api/v1/agent/audits`                             |
| Exchange a link code   | POST   | `/api/v1/auth/agent-link`                          |
| Initiate (older)       | POST   | `/api/v1/auth/agent-initiate`                      |
| Poll (older)           | GET    | `/api/v1/auth/agent-signup-status?token=<token>`   |
| Account & balance      | GET    | `/api/external/v1/account`                         |
| Add a website          | POST   | `/api/external/v1/properties`                      |
| Install status         | GET    | `/api/external/v1/properties/<propertyId>/install` |
| Remove a website       | DELETE | `/api/external/v1/properties/<propertyId>`         |
| Agents plan checkout   | POST   | `/api/external/v1/billing/agents-checkout`         |

***

## Agent Spec File

The full onboarding spec is available as a standalone markdown file that agents can load as context:

[**https://app.humblytics.com/agent.md**](https://app.humblytics.com/agent.md)

You can also open it directly in your editor:

* **Cursor**: [Add to Cursor](cursor://anysphere.cursor-deeplink/prompt?text=Fetch%20the%20Humblytics%20agent%20API%20spec%20from%20https%3A%2F%2Fapp.humblytics.com%2Fagent.md%20and%20save%20it%20as%20a%20cursor%20rule%20in%20.cursor%2Frules%2Fhumblytics.mdc) — opens Cursor and creates a rule from the spec
* **Claude Code**: download the spec and include it in your `CLAUDE.md`:

```bash
curl -o HUMBLYTICS.md https://app.humblytics.com/agent.md
```

Add it to your `CLAUDE.md`, `.cursorrules`, or system prompt and your agent will know how to onboard users automatically.

***

## Managing Your Account in the App

Accounts on the Agents plan use a simple, consistent layout in the Humblytics app. There is no side menu: your agent does the analysis over MCP, and the app is for account management.

Every page you can reach uses the same header:

| Item                 | What it does                                                                                          |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| **Humblytics logo**  | Returns to Agent home (`/agent`).                                                                     |
| **Docs**             | Opens [docs.humblytics.com](https://docs.humblytics.com) in a new tab.                                |
| **Account settings** | Opens your account settings. Hidden while you are already there.                                      |
| **Back**             | Returns to the previous page, or to Agent home if you opened the page directly. Hidden on Agent home. |
| **Log out**          | Signs you out.                                                                                        |

Agent home links straight to **Sites**, **Workspace settings**, and **API keys**. Workspace settings, site settings, the Agents page, and Connectors all open under this header. Workspace settings can open on a specific tab with `?tab=`, for example `?tab=sites`.

{% hint style="info" %}
Marketing tools and Resources are not part of the Agents plan layout. Business, Scale, trial, and Free accounts keep the full sidebar layout.
{% endhint %}

***

## Related

* [MCP & API Access](https://docs.humblytics.com/api-access-and-agents.md) — connect an agent from the Agents page, API keys and the MCP tool catalog
* [External Analytics API](https://docs.humblytics.com/external-analytics-api.md) — Query traffic, pages, clicks, forms, and funnels
* [Split Testing API](https://docs.humblytics.com/split-testing-api.md) — Create and manage A/B tests programmatically
