# HTMLvault — Full Reference

> The IT-approved HTML sharing platform: generate HTML (proposals, dashboards, lead lists, landing pages, training material) and get back a secure, trackable, optionally white-labeled link.

This is the extended companion to https://htmlvault.dev/llms.txt. It inlines the full tier comparison, the complete REST API and MCP tool reference, and integration setup, so a model can answer detailed questions without fetching additional pages.

## What HTMLvault does

Many tools now generate HTML — AI assistants (Claude, ChatGPT, Gemini), automation platforms (Zapier, Make, n8n), and data tools (Clay) — but there is no safe, branded, measurable way to share that output. HTMLvault is that layer. A user (or their AI tool) sends HTML; HTMLvault stores it, scans it for PII and secrets, returns a clean shareable link, and tracks every interaction.

Core guarantees on every link: scanned for PII/secrets before publish, never indexed by search engines (X-Robots-Tag: noindex on viewer routes), configurable auto-expiry, configurable data-retention windows (down to auto-delete), and optional password protection.

Cost model: HTMLvault funds zero AI tokens. The default scanner is regex-based and runs both client-side (pre-upload warning) and server-side. Pro+ users connect their own Anthropic/OpenAI/Google API key for an AI scan layer on top of the regex scanner. HTMLvault never pays for tokens.

## Tier comparison

### Free — $0
- links per month: 50
- link expiry: 7 days
- data retention: 90 days
- channels per link: 3
- Regex PII scanning & redaction
- Basic view count
- Never indexed by search engines
- Delete links on demand

### Pro — $12/mo ($10/mo billed annually)
- links per month: unlimited
- link expiry: 1 hr – never (configurable)
- data retention: auto-delete – 2 years (configurable)
- channels per link: unlimited
- webhooks max: 5
- Full link analytics — views, unique visitors, repeat visits
- 100K tracked views/mo included — additional views via prepaid blocks ($10 per 100K, $50 per 1M, non-expiring)
- Geo, device, scroll depth & time-on-page
- UTM & referrer tracking, server-side channel attribution
- Inject GA4, Meta Pixel, or any tracking code
- BYOK AI PII scanning (OpenAI, Anthropic, Gemini)
- REST API + MCP server
- Webhooks for real-time link events
- Branded subdomain hosting (you.hvlt.io)
- 1 white-label custom domain included, then $10/mo or $100/yr each
- Password-protected links
- Edit HTML after publishing

### Enterprise — $1,199/mo ($999/mo billed annually)
- Everything in Pro
- Unlimited seats — no per-user fees, ever
- Self-serve card checkout — no trial, no sales call
- SSO / SAML — self-serve setup via WorkOS Admin Portal (Okta, Azure AD, Google & more)
- 1M tracked views/mo included — same prepaid blocks for overage ($10 per 100K, $50 per 1M)
- 3 white-label domains included, then $10/mo or $100/yr each
- Team dashboard, admin controls & audit logs
- Custom AI scan policies per team
- Org-level API keys
- Priority support & SLA
- Invoicing (annual plans)

## Native analytics

Tracked automatically on every Pro/Enterprise link: total views, unique visitors, repeat visits, geo (country/city), device & browser, referrer source, scroll depth, time-on-page, channel attribution (server-side UTM). Users can additionally inject their own tracking codes (Google Analytics 4, Meta Pixel, or any custom script) into the link viewer.

## PII & secret scanning

The default scanner is regex-based (zero API tokens) and detects: ssn, financial, api_key, passport, address, person, dob, email, phone. It runs client-side before upload (a warning) and server-side at publish (enforced). Pro+ users can layer BYOK AI scanning on top, with selectable sensitivity (strict / balanced / permissive). Enterprise admins can set org-level scan policies with an immutable, append-only audit log and three escalation tiers (allow / warn / block).

## Integrations

HTMLvault is integration-first. Any tool that can make an authenticated HTTP request can create links. Integration names below describe interoperability only and do not imply partnership or endorsement.

- Claude (MCP + project instructions)
- ChatGPT (Custom GPT action schema)
- Zapier
- Clay
- Gemini
- any tool that can call a REST API

### Authentication

All API and MCP requests authenticate with a bearer token in the Authorization header:

```
Authorization: Bearer htmlvault_xxxxxxxxxxxxxxxxxxxxxxxx
```

Personal API keys are available to Pro and Enterprise users; org-level keys are available to Enterprise admins. Keys are generated and managed at https://htmlvault.dev/connect.

## REST API reference

Base URL: https://htmlvault.dev

### POST /api/v1/links — create a link
Publishes HTML and returns a shareable, tracked link. Re-runs PII scanning; sensitive content is blocked.

Request body (JSON):
- html (string, required) — complete self-contained HTML with inline CSS
- title (string) — short descriptive title shown in the sender's dashboard
- expiresIn (string, optional) — one of 1h, 24h, 3d, 7d, 30d; omit for no expiry
- domain (string, optional) — serve this link from one of your verified custom domains; accepts a domain id or hostname (e.g. links.acme.com). Must be an active domain on your account — returns 400 { "error": "unknown_domain" } otherwise. Omit to inherit your account's default domain.

Response (201): { "slug", "url", "created_at" }
The returned url reflects the serving domain: the domain you specified, else your account default, else HTMLvault's share domain.

### GET /api/v1/links — list your links
Query params: limit (default 20, max 100), offset (default 0).
Response (200): { "links": [ { "slug", "url", "title", "created_at", "expires_at", "view_count" } ], "total", "limit", "offset" }

### GET /api/v1/links/{slug} — get one link
Response (200): { "slug", "url", "title", "created_at", "expires_at", "view_count", "has_password" }. Returns 404 if not found or not owned.

### PATCH /api/v1/links/{slug} — update HTML
Request body: { "html": "string" } (required). Re-runs the PII scan; returns 422 with findings if sensitive data is detected.
Response (200): { "slug", "url", "updated_at" }

### DELETE /api/v1/links/{slug} — delete a link
Response (200): { "deleted": "slug" }. Returns 404 if not found or already deleted.

### POST /api/v1/links/{slug}/variants — create a channel
Creates a clean shareable URL pointing to the parent link's HTML, with UTM attribution stored server-side (no params appear in the URL). At least one of utm_source, utm_medium, or utm_campaign is required.

Request body (JSON):
- utm_source (string) — e.g. twilio
- utm_medium (string) — e.g. sms
- utm_campaign (string) — e.g. q3-promo
- utm_content (string) — also used as the channel display name in the HTMLvault UI
- utm_term (string) — optional audience or persona tag

Response (201): { "channel": { "id", "slug", "url", "utm_source", "utm_medium", "utm_campaign", "utm_content", "utm_term", "view_count" } }. Returns 400 if no UTM is provided, 403 if the free-plan channel limit is reached, 404 if the parent link is not found.

## MCP server

Endpoint: https://htmlvault.dev/api/mcp (Streamable HTTP, JSON-RPC 2.0). Authenticated with the same bearer key.

Tools exposed:
- list_links
- get_link
- create_link
- update_link
- delete_link
- scan_html
- get_analytics

Tool parameter schemas:
- list_links(limit?: int = 20, max 100; cursor?: string; created_after?: ISO8601; created_before?: ISO8601) → { links[], next_cursor, has_more }. Cursor-paginated, newest first.
- get_link(slug: string) → link metadata + html_content + url.
- get_analytics(slug: string, period?: "7d"|"30d"|"90d"|"all" = "30d") → totals (views, unique_views, repeat_views, bot_views), engagement (avg_time_on_page_seconds, avg_scroll_depth_pct), breakdowns (countries, devices, channels, referrers). Bot traffic excluded from views; reported separately as bot_views.
- create_link(html: string [required], title: string [required], expiresIn?: "1h"|"24h"|"3d"|"7d"|"30d"|"never", tracking?: "none", domain?: string) → { slug, url, title }. Runs Safe Browsing + PII policy gates; blocks on unsafe_content or pii_detected (policy=block).
- update_link(slug: string, html: string) → { slug, url, updated_at }. Same gates; slug and URL unchanged.
- delete_link(slug: string) → { deleted: slug }. Immediate, irreversible hard delete; cascades view records; blocked by legal hold.
- scan_html(html: string) → { hasSensitiveData, findings[] }. Regex scan only; never publishes.

Auth: Authorization: Bearer <key> (Pro/Enterprise). Org keys act in the org owner's workspace. Per-key rate limit (HTTP 429 with Retry-After on exceed). Full reference: https://htmlvault.dev/docs/mcp

## Webhooks

Pro/Enterprise accounts can register up to 5 endpoints (webhook settings screen) for signed, real-time HTTP notifications. Five events fire:
- link.created — authenticated uploads (web, REST, or MCP create_link). data: { slug, title, url, created_at }
- link.updated — HTML replaced in place (dashboard, REST PATCH, or MCP update_link). data: { slug, title, url, updated_at }
- link.viewed — a view of an owned link. data: { slug, view_id, is_unique, visit_number, country, city, browser, os, device_type, referrer }
- link.expired — retention cron purged the content. data: { slug, title, reason: "expiry"|"retention", expired_at }
- usage.threshold — tracked-view usage crossed the alert threshold (daily cron, once per period). data: { period, tracked, included, blockRemaining, deficit, pct, threshold }

Envelope: { id, event, timestamp, data }. The id is a stable UUID (same across retries — dedupe on it). Signing: X-HTMLvault-Signature = hex HMAC-SHA256 of the raw request body, keyed with the per-endpoint secret; verify on raw bytes before parsing with a timing-safe compare, then reject if the envelope timestamp is older than 5 minutes. Also sent: X-HTMLvault-Event and X-HTMLvault-Delivery (fresh UUID per attempt). Delivery: 1 inline attempt + 3 retries (+1m/+15m/+1h), 10s per-attempt timeout, auto-disable after 5 consecutive exhausted deliveries. Full reference: https://htmlvault.dev/docs/webhooks

### Claude Code (one line)
```
claude mcp add --transport http htmlvault https://htmlvault.dev/api/mcp --header "Authorization: Bearer htmlvault_YOUR_KEY"
```

### Claude Desktop (config)
```json
{
  "mcpServers": {
    "htmlvault": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://htmlvault.dev/api/mcp", "--header", "Authorization: Bearer htmlvault_YOUR_KEY"]
    }
  }
}
```

## ChatGPT Custom GPT action

Import the OpenAPI schema served at the connect page, with bearer auth. Operations: createHTMLvaultLink, listHTMLvaultLinks, getHTMLvaultLink, updateHTMLvaultLink, deleteHTMLvaultLink, createHTMLvaultChannel. Typical instruction: when the user says "create a link," "vault this," or "make this shareable," call createHTMLvaultLink with the HTML and a short title, then return the url.

## White-labeling

- **Pro**: branded subdomain (you.hvlt.io) plus 1 full white-label custom domain included; additional domains $10/mo or $100/yr each
- **Enterprise**: branded subdomain (you.hvlt.io) plus 3 full white-label custom domains included; additional domains $10/mo or $100/yr each

When a link is served from a custom domain, it is fully white-labeled: the URL is on the customer's own hostname and the viewer renders without HTMLvault branding. This matters for both brand consistency and email deliverability — links on the customer's own domain avoid the reputation and spam-filter penalties of a shared third-party domain.

## Who uses it

- **Sales / RevOps leaders** — proposals, pricing, demos, slide decks shared as trackable links
- **Marketing** — landing pages, email-embeddable links, campaign materials
- **Ops** — reports, dashboards, lead lists, internal training material
- **IT / Security** — the stakeholder who approves the tool; cares about PII scanning, retention, SSO, audit logs

## Contact

- Sales & general: rob@htmlvault.dev
- Support: support@htmlvault.dev
- Business address: 704 13th St East, Suite 600, Whitefish, MT 59937