# MyFunnelAPI

> Build and host funnels at edge speed

Base URL: https://api.myfunnelapi.com

Authentication: `Authorization: Bearer <your_api_key>`

Prerequisites: Before creating a funnel you MUST (1) own a domain registered via mydomainapi.com, and (2) have an Organization in my-api-hq that supplies the brand context.

How it works: The AI planner produces a multi-page site graph (landing page + auto-generated legal pages). Confirm the plan — the server automatically builds all pages in the background. Then preview or publish to the custom domain at the edge.

Workflow summary:
1. POST /funnel/funnels/prompt/plan — returns {status: ready, plan} or {status: needs_clarification, questions}.
2. POST /funnel/funnels/prompt/plan/answers — provide answers to blocking questions (repeat until ready).
3. POST /funnel/funnels/prompt/plan/confirm — creates the funnel and auto-starts all page builds. Returns {funnel_id, build_jobs: {page_key: job_id}}.
4. Poll GET /funnel/jobs/{job_id} per page until completed.
5. POST /funnel/funnels/{id}/preview or /publish.

> **Note for AI Agents:** Legal pages are generated automatically. For lead capture forms you need a webhook slug from my-webhook-api — the planner will ask for it if missing.

## Key Blog Posts
- [The 100ms Conversion Rule: Edge-Serving Funnels](https://myfunnelapi.com/blog/100ms-conversion-rule-edge-serving): Measuring the impact of Time to First Byte (TTFB) on user psychology, and why traditional cloud architectures fail modern funnels.
- [First-Party Cookie Persistence Done Right](https://myfunnelapi.com/blog/first-party-cookie-persistence-done-right): A deep dive into Safari's Intelligent Tracking Prevention (ITP) and how to architect server-set cookies that survive the 7-day cap.
- [Headless vs. Visual Builders: Scaling 10,000 Pages](https://myfunnelapi.com/blog/headless-vs-visual-builders-scaling): Why monolithic page builders collapse under enterprise scale, and how decoupled API-driven architectures enable programmatic deployments.
- [Edge-Side Rendering for Real-Time Personalization](https://myfunnelapi.com/blog/edge-side-rendering-real-time-personalization): Modifying the DOM before the first byte: How edge workers enable microsecond personalization without the SEO penalties of React.
- [Streaming Conversion Events Without JavaScript](https://myfunnelapi.com/blog/streaming-conversion-events-without-javascript): Bypassing ad-blockers and building resilient server-to-server data pipelines for deterministic attribution.


## Agent Onboarding

To use this or any other MyAPIHQ service as an autonomous agent, follow these steps:

1. **Register an Agent Account**:
   Create an agent account. Returns `account_id`, `pin`, and a `token` (JWT) in one call — no email or human required.
   ```bash
   curl -X POST https://api.myapihq.com/hq/account/agent/create \
     -H "Content-Type: application/json" \
     -d '{"label": "my-agent"}'
   ```

2. **Create a Permanent API Key**:
   Use the `token` from step 1 to create a workspace-scoped API key (`hq_live_...`).
   ```bash
   curl -X POST https://api.myapihq.com/hq/account/create/key \
     -H "Authorization: Bearer <token_from_step_1>" \
     -H "Content-Type: application/json" \
     -d '{"name": "my-agent-key"}'
   ```

3. **Authenticate**:
   All subsequent requests must include: `Authorization: Bearer <your_api_key>`.
   The JWT token from step 1 is valid for account and billing endpoints only.
   All service calls (orgs, funnels, email, domains) require the API key from step 2.

## Endpoints

### GET /funnel/jobs/{id}
**Get Job Status**
Poll a background build job. Returns status (processing/completed/failed). On completion, result contains page_key and funnel_id.

**Parameters:**
- `id` (path):  (type: string, Required)

**Response (JSON):**
```json
{
  "id": string,
  "status": string (processing|completed|failed),
  "result": {
    "funnel_id": string,
    "page_key": string
  },
  "error": string
}
```


### POST /funnel/funnels/prompt/plan
**Plan Funnel**
Step 1 of 3. The AI reads the org's brand context and available webhooks, then returns either a ready site-graph plan or a list of blocking clarification questions. Non-blocking items (colors, font) are inferred silently.

**Request Body (JSON):**
```json
{
  "org_id": string - UUID of the organization (supplies brand context). (Required),
  "domain": string - Domain the funnel will be hosted on. (Required),
  "prompt": string - Natural language description of the site. (Required)
}
```

**Response (JSON):**
```json
{
  "status": string (ready|needs_clarification),
  "plan": object - Site graph plan (present when status=ready).,
  "questions": Array<{
    "id": string,
    "question": string,
    "reusable_for_org": boolean
  }>
}
```


### POST /funnel/funnels/prompt/plan/answers
**Answer Clarification Questions**
Step 2 of 3 (only if plan returned needs_clarification). Send answers to blocking questions. Answers tagged reusable_for_org are written back to the org record. Returns the same discriminated union as /plan — repeat until status=ready.

**Request Body (JSON):**
```json
{
  "org_id": string (Required),
  "domain": string (Required),
  "prompt": string (Required),
  "answers": object - Map of question_id → answer string. (Required)
}
```

**Response:** Plan ready or further clarification needed (same schema as /plan).


### POST /funnel/funnels/prompt/plan/confirm
**Confirm Plan**
Step 3 of 3. Converts the plan into a site graph, creates the funnel in the database, registers the org webhook, writes brand tokens back to the org, and automatically kicks off background HTML generation for all pages. Returns funnel_id and a map of page_key → job_id to poll for build completion.

**Request Body (JSON):**
```json
{
  "org_id": string (Required),
  "domain": string (Required),
  "prompt": string (Required),
  "plan": object - The plan object returned by /plan or /plan/answers. (Required)
}
```

**Response (JSON):**
```json
{
  "funnel_id": string,
  "build_jobs": object - Map of page_key → job_id. Poll GET /funnel/jobs/{job_id} per page.
}
```


### POST /funnel/funnels/{id}/edit
**Edit Page**
Regenerate a single page with a natural language instruction. Returns a job_id to poll.

**Parameters:**
- `id` (path):  (type: string, Required)

**Request Body (JSON):**
```json
{
  "page_key": string - Graph key of the page to edit. (Required),
  "prompt": string - Natural language edit instruction. (Required)
}
```

**Response (JSON):**
```json
{
  "job_id": string
}
```


### GET /funnel/funnels
**List Funnels**
List all funnels for the authenticated account.

**Response:** Array of funnels


### GET /funnel/funnels/{id}
**Get Funnel**
Get funnel metadata (domain, org, created_at). Does not include the site graph or HTML — use /graph for that.

**Parameters:**
- `id` (path):  (type: string, Required)

**Response:** Funnel details

---
### DELETE /funnel/funnels/{id}
**Delete Funnel**
Permanently delete a funnel and purge all KV snapshots (preview + published, all slugs).

**Parameters:**
- `id` (path):  (type: string, Required)


### POST /funnel/funnels/{id}/preview
**Preview Funnel**
Renders all built pages to HTML and writes them to KV as preview snapshots (funnel:{id}:preview:{slug}). Returns a single root preview URL. All pages must be built first.

**Parameters:**
- `id` (path):  (type: string, Required)

**Response (JSON):**
```json
{
  "preview_url": string - Root preview URL. Append slug to access other pages, e.g. /preview/{id}/privacy.
}
```


### POST /funnel/funnels/{id}/publish
**Publish Funnel**
Renders all pages and writes them to KV as published snapshots (funnel:{id}:published:{slug}). Maps the domain to the funnel. Rate-limited to 10 publishes/hour per funnel and 50/hour per account. Requires a domain registered via mydomainapi.com.

**Parameters:**
- `id` (path):  (type: string, Required)

**Response (JSON):**
```json
{
  "status": string,
  "url": string,
  "propagation_delay_seconds": integer
}
```


### GET /funnel/funnels/{id}/publish/status
**Publish Status**
Returns status: 'propagating' (within 60s of last publish) or 'live'.

**Parameters:**
- `id` (path):  (type: string, Required)

**Response:** Publish status


### POST /funnel/funnels/{id}/event
**Fire Funnel Event**
Called from funnel page JS on CTA interaction. Resolves the webhook slug and relays the payload fire-and-forget. Unauthenticated.

**Parameters:**
- `id` (path):  (type: string, Required)

**Request Body (JSON):**
```json
{
  "webhook": string - Webhook slug. (Required),
  "fields": object - Form field values keyed by field name. (Required)
}
```


### POST /hq/billing/setup-payment
**Setup Payment Method**
Generates a Stripe Checkout Session URL to save a card. The user must visit this URL, enter their card, and complete the setup. A webhook will automatically save the card to the account.

**Response (JSON):**
```json
{
  "success": boolean,
  "data": {
    "url": string
  },
  "error": string,
  "meta": object
}
```


## Pricing

Pay per use. No subscription.

---
## Ecosystem Integration
This service is part of the MyAPIHQ ecosystem. You authenticate using an API Key generated from your MyAPIHQ account.
To view the full list of available services (like domain registration, funnel building, transactional email, object storage, etc.), fetch [https://myapihq.com/llms.txt](https://myapihq.com/llms.txt).