# 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](/external-analytics-api.md) and [Split Testing API](/split-testing-api.md).

***

## 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](/external-analytics-api.md) — Query traffic, pages, clicks, forms, and funnels
* [Split Testing API](/split-testing-api.md) — Create and manage A/B tests programmatically


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.humblytics.com/agent-onboarding-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.