# Yuzool Agent API (MVP)

## Paid-first requirement
Agent execution is blocked until account is paid.

Before running agents, complete Stripe onboarding:
- https://buy.stripe.com/28E9AM0c76fO3Xx4ja4gg0J
- https://stripe.dev/agent-toolkit
- https://stripe.com/resources/more/link-wallets-for-agents
- https://stripe.com/agentic-commerce

Starting plan: **Agent Starter ($19/month)** with plan id `agent_starter_monthly_19`.

Then:
1. `POST /api/agents/billing/activate` (or Stripe webhook sync)
2. `POST /api/agents/access` with `{ "enabled": true }`
3. Create scoped keys from `/agent-keys.html` or `POST /api/agents/keys`

## Base paths
- REST: `/api/agents/*`
- MCP tool manifest: `/api/agents/mcp`

## Auth
- Header: `Authorization: Bearer <api_key>` or `x-api-key: <api_key>`
- Agent keys are scoped and revocable.
- Optional IP allowlist can be set via `POST /api/agents/network/allowlist`.

## Endpoints

### Plans + Billing + Access
- `GET /api/agents/plans`
- `GET /api/agents/billing/links`
- `POST /api/agents/billing/activate`
- `POST /api/agents/billing/webhooks/stripe`
- `POST /api/agents/access`
- `POST /api/agents/network/allowlist`

### Agent Keys
- `GET /api/agents/keys`
- `POST /api/agents/keys`
- `POST /api/agents/keys/:keyId/revoke`
- Keys include `last_used_at` and optional per-key `allowed_ips`.

### Outcome endpoints
- `POST /api/agents/invoice/create`
- `POST /api/agents/invoice/draft`
- `POST /api/agents/invoice/confirm`
- `POST /api/agents/widgets/generate`
- `POST /api/agents/widgets/revise`
- `POST /api/agents/storefront/build`
- `POST /api/agents/content/repurpose`
- `POST /api/agents/membership/build`
- `POST /api/agents/clips/factory`
- `POST /api/agents/directory/build`
- `POST /api/agents/outreach/build`
- `POST /api/agents/business-box/build`
- `POST /api/agents/business-box/revise`
- `POST /api/agents/intent`
- `GET /api/agents/status/:jobId`
- `GET /api/agents/usage`

### Ops endpoints (master key only)
- `GET /api/agents/ops/summary`
- `GET /api/agents/ops/jobs`
- `GET /api/agents/ops/webhooks`
- `GET /api/agents/ops/audit`
- `POST /api/agents/ops/webhooks/replay`
- `POST /api/agents/ops/queue/process`

### Webhook verification helper
- `POST /api/agents/webhook/verify-example`

### MCP
- `GET /api/agents/mcp`
- Includes aliases for explicit skills: `create_landing_page`, `send_invoice`, `get_invoice_status`.
- Includes storefront tools: `build_storefront`, `create_checkout_flow`.
- Includes content tools: `repurpose_content`, `content_repurposing_studio`.
- Includes membership tools: `build_membership_site`, `create_course_membership`.
- Includes clip tools: `youtube_clip_factory`, `generate_social_clips`.
- Includes directory tools: `build_directory_marketplace`, `create_marketplace_kit`.
- Includes outreach tools: `build_outreach_campaign`, `create_outbound_sequence`.
- Includes business template tools: `build_business_in_a_box`, `launch_business_template`.
- Includes business revision tool: `revise_business_in_a_box`.

## Usage controls
- Monthly quota metering by endpoint bucket.
- 429 returned when quota is exhausted.
- Audit events recorded for auth decisions, key operations, and billing webhook events.
- `GET /api/agents/usage` returns current bucket usage, limits, and remaining quotas.
- Overage policy is explicit in `overage_policy` (hard cap, no auto-bill by default).

## Idempotency
For create-style endpoints, pass `Idempotency-Key` header.

## Natural-language invoice flow
One-call draft:
```bash
curl -X POST https://www.yuzool.com/api/agents/intent \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{"command":"invoice a client Momentum Labs for 1200 usd tax 10% due 2026-05-30 billing@momentumlabs.com"}'
```

## Natural-language Business-in-a-Box examples
Route these through `POST /api/agents/intent`:

- `launch a business-in-a-box for a coaching business`
- `launch a business-in-a-box for an agency lead gen system`
- `launch a business-in-a-box for a digital product shop`
- `launch a business-in-a-box for a newsletter biz`
- `launch a business-in-a-box for a local service business`
- `revise my business-in-a-box for stronger upsells and retention`

Confirm send:
```bash
curl -X POST https://www.yuzool.com/api/agents/invoice/confirm \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{"job_id":"job_xxx","action":"send"}'
```

## Widget/page revise flow
```bash
curl -X POST https://www.yuzool.com/api/agents/widgets/revise \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{"instruction":"Make CTA button text Start Free","source_html":"<section>...</section>","mode":"widget","section_patches":[{"field":"button_label","value":"Start Free"},{"field":"button_url","value":"/start"}]}'
```

## Storefront builder + checkout ops
```bash
curl -X POST https://www.yuzool.com/api/agents/storefront/build \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{
    "prompt":"Build a storefront for my launch templates",
    "store_name":"Yuzool Launch Store",
    "products":[
      {"name":"Starter Pack","description":"20 templates","price":79,"currency":"USD"},
      {"name":"Pro Pack","description":"60 templates + playbook","price":199,"currency":"USD"}
    ]
  }'
```

### Real Stripe Checkout Sessions
- Set `STRIPE_SECRET_KEY` (or `YUZOOL_STRIPE_SECRET_KEY`) in production environment variables.
- When present, `/api/agents/storefront/build` creates real Stripe Checkout Sessions per product and returns `checkout_session_id` + hosted `checkout_url`.
- When missing, response falls back to safe payment links and includes `checkout.warnings`.

## Content repurposing studio
```bash
curl -X POST https://www.yuzool.com/api/agents/content/repurpose \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{
    "prompt":"Launch post for our new creator CRM bundle",
    "audience":"freelance creators",
    "tone":"calm and practical"
  }'
```

## Course/membership mini-sites
```bash
curl -X POST https://www.yuzool.com/api/agents/membership/build \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{
    "prompt":"Build a mini site for my AI freelancing academy membership",
    "program_name":"AI Freelancing Academy",
    "monthly_price":39
  }'
```

## YouTube clip factory
```bash
curl -X POST https://www.yuzool.com/api/agents/clips/factory \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{
    "prompt":"Turn this YouTube episode into social clips",
    "duration":"00:42:00",
    "clip_count":5,
    "platforms":["youtube_shorts","instagram_reels","tiktok"]
  }'
```

If you pass timestamped transcript lines (for example `00:03:12 ...`), the API switches to `extraction_mode: transcript_aware` and anchors clips to real spoken moments.

## Directory + marketplace kits
```bash
curl -X POST https://www.yuzool.com/api/agents/directory/build \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{
    "prompt":"Build a searchable directory with submission form and paid featured listings",
    "directory_name":"Creator Tools Atlas",
    "categories":["Analytics","Automation","Design"],
    "monetization":{"featured_price":59,"currency":"USD"}
  }'
```

## Automated outreach campaigns
```bash
curl -X POST https://www.yuzool.com/api/agents/outreach/build \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{
    "prompt":"Build an outbound campaign for creator analytics leads",
    "campaign_name":"Creator Analytics Outreach",
    "leads":[
      {"name":"Alex Rivera","email":"alex@momentumlabs.co","company":"Momentum Labs","role":"Founder"},
      {"name":"Dana Kim","email":"dana@northpeak.studio","company":"Northpeak Studio","role":"Head of Marketing"}
    ]
  }'
```

## Business-in-a-Box templates
```bash
curl -X POST https://www.yuzool.com/api/agents/business-box/build \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{
    "prompt":"launch a business in a box for a coaching business",
    "template":"coaching_business"
  }'
```

## Revise Business-in-a-Box
```bash
curl -X POST https://www.yuzool.com/api/agents/business-box/revise \
  -H "content-type: application/json" \
  -H "x-api-key: <agent_key>" \
  --data '{
    "prompt":"launch a digital product shop for creator templates",
    "template":"digital_product_shop",
    "instruction":"Increase conversion with stronger upsell and retention loops",
    "focus_areas":["pricing presentation","upsell sequencing","email recovery"]
  }'
```

## Ops dashboard
- Internal dashboard: `/agent-ops` (requires master key input)
- Shows queue/job state, webhook retries/dead-letter candidates, and audit events.
- Production guardrail: set `YUZOOL_AGENT_OPS_ENABLED=true` to enable `/api/agents/ops/*`.

## Scheduled queue sweep + alerts
- Netlify scheduled function: `agent-queue-sweep` runs every 15 minutes.
- It calls `/api/agents/ops/queue/process` and `/api/agents/ops/summary`.
- Optional alert sink: set `YUZOOL_ALERT_WEBHOOK_URL` to receive JSON alerts when dead-letter candidates or timed-out jobs are detected.

## Signed webhooks
Webhook deliveries include:
- `x-yuzool-event`
- `x-yuzool-attempt`
- `x-yuzool-timestamp`
- `x-yuzool-signature`

Signature format: `sha256=<hmac_hex>` where payload is signed as:
`<timestamp>.<raw_json_body>`

Secret: `YUZOOL_WEBHOOK_SECRET` (falls back to `dev-webhook-secret` locally).

## Storage backend
- Automatic adapter:
  - Supabase when `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY` are set
  - Local JSON fallback when not set

## Local run
```bash
YUZOOL_AGENT_API_KEY=devkey YUZOOL_WEBHOOK_SECRET=whsec_test node scripts/serve-agent-api.mjs
```

## Agent prompt packs
- Claude: `api/agents/examples/prompts/claude-system-prompt.md`
- Cursor: `api/agents/examples/prompts/cursor-instructions.md`
- OpenAI Agents SDK: `api/agents/examples/prompts/openai-agents-sdk.md`

## 10-line bootstrap
```text
You are connected to Yuzool outcome APIs.
Base URL: https://www.yuzool.com
Tool discovery: GET /api/agents/mcp
Auth: Authorization: Bearer <AGENT_KEY>
Start flow: POST /api/agents/intent (natural language first)
Invoice safe flow: POST /api/agents/invoice/draft -> POST /api/agents/invoice/confirm
Landing/widget flow: POST /api/agents/widgets/generate then /api/agents/widgets/revise
Storefront flow: POST /api/agents/storefront/build for full page + checkout ops output
Job polling: GET /api/agents/status/:jobId
If 402: prompt user to activate Agent Starter.
If 429: read overage_policy and suggest upgrade or retry next cycle.
```