# Agent Onboarding API

The Agent Onboarding API lets AI agents sign up users, handle plan selection and payment, and receive an API token — 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

The signup flow has two parts:

1. **The agent** calls `/api/v1/auth/agent-initiate` to create a session and get a unique verification URL.
2. **The user** opens that URL in their browser to verify identity and complete payment.
3. **The agent** polls until the session is complete, then receives an `authToken` for all subsequent API calls.

***

## Step 1 · Initiate Signup

Create a signup session for a new user.

**Request**

```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" }'
```

**Parameters**

| Name    | Type   | Required | Description          |
| ------- | ------ | -------- | -------------------- |
| `email` | string | Yes      | User's email address |
| `name`  | string | Yes      | User's full name     |

**Response (201)**

```json
{
  "token": "<session-token>",
  "verifyUrl": "https://app.humblytics.com/agent-verify?token=<session-token>",
  "expiresAt": 1234567890000
}
```

**Error Responses**

| Status | Body                           | Meaning                      |
| ------ | ------------------------------ | ---------------------------- |
| 409    | `{ "error": "user_exists" }`   | Email already has an account |
| 400    | `{ "error": "invalid_email" }` | Email format is invalid      |

{% hint style="info" %}
The session expires in **10 minutes** if the user doesn't open the verification link.
{% endhint %}

***

## Step 2 · User Verification

Tell the user to open the verification URL in their browser. The page will:

1. Silently verify the user is human
2. Create their Humblytics account and set a browser session
3. Ask them to choose **Business Monthly ($79/mo)** or **Business Annual ($65/mo, save $168/yr)**
4. Redirect to Stripe to complete payment
5. Show a confirmation page

{% 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 Completion

Poll every 3–5 seconds until `status` is `"complete"` or the session expires.

**Request**

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

**While waiting**

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

**When complete**

```json
{
  "status": "complete",
  "authToken": "<jwt>"
}
```

**Error Responses**

| Status | Meaning                                      |
| ------ | -------------------------------------------- |
| 404    | Token not found                              |
| 410    | Session expired — ask the user to start over |

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

***

## Step 4 · Use the Token

All subsequent API calls use the token as a Bearer header:

```http
Authorization: Bearer <authToken>
```

This token works with all Humblytics API endpoints including the [External Analytics API](https://docs.humblytics.com/external-analytics-api) and [Split Testing API](https://docs.humblytics.com/split-testing-api).

***

## Step 5 · Add a Website

With the token, the agent can immediately add a website to the account.

**Request**

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

**Response**

```json
{
  "propertyId": "<property-id>",
  "scriptId": "<script-id>"
}
```

Install the tracking script on the user's site:

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

***

## Step 6 · Stripe Payment Links (Fallback)

If the user skipped payment during signup, send them directly to Stripe:

| Plan    | URL                                                                      |
| ------- | ------------------------------------------------------------------------ |
| Monthly | `https://buy.stripe.com/6oU9AS4TVdaQafZ9tS2Nq0k?prefilled_email=<email>` |
| Annual  | `https://buy.stripe.com/8x2cN40DF4EkafZ49y2Nq0j?prefilled_email=<email>` |

***

## Quick Reference

| Step                | Method | Endpoint                                         |
| ------------------- | ------ | ------------------------------------------------ |
| Initiate signup     | POST   | `/api/v1/auth/agent-initiate`                    |
| Poll for completion | GET    | `/api/v1/auth/agent-signup-status?token=<token>` |
| Add a website       | POST   | `/api/v1/add-custom-site`                        |
| List websites       | GET    | `/api/v1/property/all`                           |
| Billing status      | GET    | `/api/v1/billing/status`                         |

***

## 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**: Run `curl -o HUMBLYTICS.md https://app.humblytics.com/agent.md` then include in your CLAUDE.md

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

***

## Related

* [External Analytics API](https://docs.humblytics.com/external-analytics-api) — Query traffic, pages, clicks, forms, and funnels
* [Split Testing API](https://docs.humblytics.com/split-testing-api) — Create and manage A/B tests programmatically