> 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/api-access-and-agents.md).

# API Access & Agent Setup

The **API Access** page in the Humblytics dashboard is your activation console for programmatic access and AI coding agents. Instead of a static reference sheet, it walks you through a four-step guided flow: generate a key, pick your agent, install marketing skills, and verify your first API call.

Open it from the sidebar under **Utilities → API**.

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

***

## Overview

The page is organized as a **progress rail** at the top and a two-column layout below:

* **Left column** — the four activation steps (accordion cards). Future steps stay locked until you complete the current one.
* **Right column** — a sticky **Your setup** pane with your Property ID, Base URL, and one-click copy buttons for install prompts, skills setup, and your first test command.

Below the steps you will also find a **Reference: example curl** card (with an env-var vs literal toggle) and a collapsible **Endpoints** reference grouped by the CRO loop.

{% hint style="info" %}
Humblytics does **not** ship an MCP server. The supported agent entry points are the open-source [humblytics-marketing-skills](https://github.com/Humblytics/humblytics-marketing-skills) repo plus the property-scoped REST API documented in the [External Analytics API](/external-analytics-api.md).
{% endhint %}

***

## Step 1 · Generate key

Create a property-scoped API key. This is the only step that unlocks the rest of the flow.

**What you can do**

* Click **Generate your first key** (or **Generate another key**) and give the key a name (for example, `Production`, `Claude Agent`, or `CI/CD`).
* Copy the full key immediately when it is shown — it is displayed **once** at creation and cannot be retrieved later.
* View active keys (name, prefix, last-used date) and revoke keys you no longer need.
* Expand the **Revoked** section to see previously revoked keys.

**Security practices**

The page surfaces these rules prominently:

* Store the key in a `.env` file that is listed in `.gitignore`.
* Never paste the key into chat, `CLAUDE.md`, `AGENTS.md`, or any committed file.
* Always reference `$HUMBLYTICS_API_KEY` in commands — never inline the literal value.

{% hint style="warning" %}
API key management requires the **Plus** plan or higher. Free accounts see an upgrade prompt on this step.
{% endhint %}

***

## Step 2 · Pick your agent

Copy a secure **install prompt** tailored to your AI coding tool. The prompt references `$HUMBLYTICS_API_KEY` from the environment — it never embeds your literal key.

| Tab             | Best for                             | Reads from                   |
| --------------- | ------------------------------------ | ---------------------------- |
| **Claude Code** | Anthropic's terminal coding agent    | `CLAUDE.md`                  |
| **Cursor**      | The Cursor editor                    | `.cursorrules` / `AGENTS.md` |
| **Generic**     | Any agent that loads a system prompt | Your agent's context file    |

Each install prompt includes:

* A link to fetch the full API spec from `https://app.humblytics.com/agent.md`
* Step-by-step `.env` setup instructions for your tool
* A safe example `curl` against `/traffic/summary`
* A quick-reference list of key endpoints and query parameters

Click **Copy install prompt**, then paste it into your agent's context file or session.

***

## Step 3 · Install the skills

Install the **12 Humblytics marketing skills** from the open-source [humblytics-marketing-skills](https://github.com/Humblytics/humblytics-marketing-skills) repository. Skills follow the [Agent Skills standard](https://code.claude.com/docs/en/skills) — each skill is a directory containing a `SKILL.md`.

Click **Add 12 skills to your agent** to copy a natural-language setup prompt. Paste it into your coding agent and it will clone the repo, copy skills into the correct folder, and wire up credentials.

### Skills catalog

| Skill                  | Description                                          | API-connected |
| ---------------------- | ---------------------------------------------------- | ------------- |
| `cro-optimizer`        | Live funnel analysis + scored A/B test hypotheses    | Yes           |
| `ab-test-generator`    | Generate & launch no-code split tests from analytics | Yes           |
| `heatmap-analyst`      | Click, scroll & rage-click friction analysis         | Yes           |
| `revenue-attributor`   | Ad spend to Stripe revenue, ROAS + reallocation      | Yes           |
| `funnel-reporter`      | End-to-end SaaS funnel reporting                     | Yes           |
| `page-cro`             | 10-point landing page conversion audit               | No            |
| `email-sequences`      | Onboarding, nurture & re-engagement drips            | No            |
| `seo-strategist`       | Keyword research, gaps, on-page + technical SEO      | No            |
| `marketing-strategist` | Funnels, GTM, positioning, growth strategy           | No            |
| `copywriting`          | Conversion copy for pages, emails & ads              | No            |
| `ad-expert`            | Paid ads: Meta, Google, TikTok, LinkedIn             | No            |
| `content-strategist`   | Articles, newsletters, social, video, SEO            | No            |

**5 skills** read live Humblytics data via the API. **7 skills** provide strategy and copy guidance without API calls.

The five API-connected skills read `HUMBLYTICS_API_KEY` and `HUMBLYTICS_PROPERTY_ID` from your `.env` file.

### Where skills are installed

| Agent       | Skills directory   | Scope           |
| ----------- | ------------------ | --------------- |
| Claude Code | `~/.claude/skills` | All projects    |
| Cursor      | `.cursor/skills`   | Current project |
| Generic     | `.agent/skills`    | Current project |

### Skills chain together

Once installed, you can chain skills with natural-language prompts:

| Prompt                                        | Skill chain                                                |
| --------------------------------------------- | ---------------------------------------------------------- |
| "Find my worst-performing page and fix it"    | CRO Optimizer → Page CRO → A/B Test Gen                    |
| "Weekly performance report + recommendations" | Funnel Reporter → CRO Optimizer                            |
| "Cut my worst ad & replace the landing page"  | Funnel Reporter → CRO Optimizer → A/B Test Gen → Ad Expert |

Browse the full directory at [humblytics.com/skills](https://humblytics.com/skills) or view the source on [GitHub](https://github.com/Humblytics/humblytics-marketing-skills).

***

## Step 4 · Verify it works

Click **Test connection** to fire a real `GET /properties/{propertyId}/traffic/summary` request against your property for the last 7 days.

On success you will see:

* A **Connection verified** confirmation (200 OK)
* Summary metrics: page views, unique visitors, and sessions
* The full JSON response

This first successful call marks activation complete.

You can also copy a **first test command** from the setup pane and run it manually in your terminal:

```bash
curl -H "Authorization: Bearer $HUMBLYTICS_API_KEY" \
  "https://app.humblytics.com/api/external/v1/properties/$HUMBLYTICS_PROPERTY_ID/traffic/summary?start=2025-01-01T00:00:00Z&end=2025-01-31T23:59:59Z&timezone=America/New_York"
```

{% hint style="info" %}
Always use the **Env var** mode in the Reference curl card for committed commands. Literal mode is for one-off testing only.
{% endhint %}

***

## Your setup pane

The sticky right column keeps your connection details and copy actions in one place:

| Field / action              | Description                                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| **API key**                 | Shows active key count and prefix. Link to generate a new key if you need to copy one again. |
| **Property ID**             | Your property identifier — click to copy.                                                    |
| **Base URL**                | `https://app.humblytics.com/api/external/v1/` — click to copy.                               |
| **Copy install prompt**     | Step 2 payload for your selected agent tab.                                                  |
| **Copy skills setup**       | Step 3 payload to install all 12 marketing skills.                                           |
| **Copy first test command** | Safe env-var curl for `/traffic/summary`.                                                    |
| **Setup progress**          | Tracks completion across all four steps (persisted per property in your browser).            |

***

## Endpoints reference

The page includes a collapsible endpoint reference grouped by the **CRO loop**:

| Group       | Tagline                               | What it covers                                                                                         |
| ----------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **Read**    | analytics, recommendations & heatmaps | Traffic summary/trends/breakdown, pages, clicks, forms, split-test recommendations, funnel suggestions |
| **Decide**  | funnels & split-test results          | Funnel queries, Sankey diagrams, saved funnels, split-test listing and details                         |
| **Ship**    | split-tests & variants                | Create/update/stop split tests, create/delete saved funnels                                            |
| **Onboard** | properties & connectors               | Ads attribution, Google Ads connections, Meta Ads connections                                          |

For full endpoint documentation, parameter tables, and sample responses, see:

* [External Analytics API](/external-analytics-api.md) — traffic, pages, clicks, forms, funnels
* [Split Testing API](/split-testing-api.md) — recommendations, experiment creation, management
* [Ads Attribution API](/ads-attribution-api.md) — per-campaign funnel attribution
* [Ads Connections API](/ads-connections-api.md) — Google Ads and Meta Ads connector data

***

## Related

* [External Analytics API](/external-analytics-api.md) — full analytics endpoint reference
* [Split Testing API](/split-testing-api.md) — programmatic A/B testing
* [Agent Onboarding API](/agent-onboarding-api.md) — sign up users and add websites from an agent
* [humblytics-marketing-skills on GitHub](https://github.com/Humblytics/humblytics-marketing-skills) — open-source agent skills repo