keitaro

Keitaro — Tracker Management for Affiliate Marketers

Full Keitaro tracker control via natural language. Manage campaigns, flows, landings, reports, and optimization through the Admin API.

Quick Reference

| Command | What it does | |---------|-------------| | /keitaro setup | Connect to Keitaro API, verify access, save config | | /keitaro campaigns | Create/list/update/delete campaigns | | /keitaro flows | Manage traffic flows, weights, filters, A/B tests | | /keitaro reports | Analytics: ROI, CR, EPC by campaign/flow/landing/geo/device | | /keitaro optimize | Auto-optimize: kill losers, scale winners, rebalance weights | | /keitaro landing | Generate landing/prelanding content for any vertical | | /keitaro audit | Audit campaign setup: dead flows, broken postbacks, misconfig |

Context Intake (Required — Always Do This First)

Before any operation, ensure Keitaro API connection is configured. Check for KEITARO_URL and KEITARO_API_KEY environment variables.

If not set, run /keitaro setup first.

Ask these questions upfront if not already known:

1. Vertical — What are you running? Gambling, Crypto, Nutra, Dating, Finance,

Sweepstakes, E-commerce, Health/Medical, Insurance, Software, Other

1. GEOs — Target countries
2. Traffic source — Where traffic comes from (Facebook, Google, TikTok, Push, Pop, Native, SEO)
3. Goal — What metric matters most? ROI, CR, EPC, Revenue, Volume

If the user provides context upfront (e.g. "create campaign for gambling DE"), extract it and proceed without re-asking.

API Connection

All API calls go through the Keitaro Admin API:

Base URL: {KEITARO_URL}/admin_api/v1
Headers: Api-Key: {KEITARO_API_KEY}

Use the scripts/keitaro_api.py helper for all API operations. Run via: python3 ~/.claude/skills/keitaro/scripts/keitaro_api.py <action> [args]

Orchestration Logic

When the user invokes /keitaro:

1. Check API connection — verify KEITARO_URL and KEITARO_API_KEY are set
2. Parse command — route to appropriate sub-skill
3. Collect context — vertical, GEO, traffic source if needed
4. Execute — call Keitaro API via helper script
5. Report — show results in clean, readable format

For /keitaro audit, spawn subagents in parallel:

• campaign-analyzer — analyze campaign performance across all campaigns
• flow-optimizer — check flow health, dead landings, weight distribution

Reference Files

Load on-demand as needed — do NOT load all at startup.

Path resolution: All references are installed at ~/.claude/skills/keitaro/references/.

• references/keitaro-api.md — Full Admin API reference (endpoints, methods, params)
• references/verticals.md — Vertical-specific benchmarks (CR, EPC, ROI targets by vertical+GEO)
• references/optimization-rules.md — Kill rules, scaling rules, weight distribution logic
• references/landing-specs.md — Landing page specs and patterns by vertical
• references/flow-patterns.md — Common flow patterns (white/offer, A/B, geo-split, device-split)

Safety System

The API helper has built-in safety at 3 levels:

Level 1: Dry Run Mode

Always use --dry-run first when unsure about an operation. It shows exactly what API calls would be made without executing them.

python3 ~/.claude/skills/keitaro/scripts/keitaro_api.py --dry-run campaign disable --id 12

Level 2: Automatic Snapshots

Before any destructive operation (disable, delete, update stream), the script automatically saves a JSON snapshot of the current state to ~/.claude/keitaro-snapshots/. This allows manual rollback if something goes wrong.

Level 3: Live Traffic Detection

Before modifying a campaign or stream, the script checks for recent traffic. If clicks were detected in the last 24h, it prints a warning:

[SAFETY] WARNING: Campaign #12 has LIVE TRAFFIC!
[SAFETY]   Last 24h: 5,432 clicks, $271.60 spent
[SAFETY]   Modifying this campaign may affect active traffic.

Level 4: Last-Flow Protection

Disabling the only active flow in a campaign is BLOCKED by default. This prevents accidentally killing all traffic to a campaign. Use --force to override (you must explicitly confirm).

Quality Gates

Hard rules — never violate these:

• ALWAYS use --dry-run first for any destructive operation you're not 100% sure about
• Never delete a campaign without explicit user confirmation
• Never change flows on campaigns with active traffic without warning the user first
• Kill Rule: flag any flow/landing with ROI < -30% over 100+ clicks for pause
• Scale Rule: flows with ROI > 30% over 200+ clicks are candidates for weight increase
• Always verify postback URL is configured before marking campaign as ready
• Never expose API key in outputs or logs
• Always show estimated impact before bulk operations ("this will affect X campaigns")
• Never disable the last active flow in a campaign (blocks traffic completely)
• For bulk operations (more than 3 items), always run --dry-run first, show output to user, then execute

Optimization Thresholds

Default thresholds (user can override):

| Metric | Kill | Warning | Good | Scale | |--------|------|---------|------|-------| | ROI | < -30% | -30% to 0% | 0% to 30% | > 30% | | CR | < 0.5% | 0.5% to 1% | 1% to 3% | > 3% | | EPC | < $0.05 | $0.05-0.15 | $0.15-0.50 | > $0.50 | | Min clicks for decision | 100 | — | — | 200 |

These vary by vertical — load references/verticals.md for vertical-specific thresholds.

Sub-Skills

This skill orchestrates 7 specialized sub-skills:

1. keitaro-setup — API connection and initial configuration
2. keitaro-campaigns — Campaign CRUD operations
3. keitaro-flows — Flow and traffic distribution management
4. keitaro-reports — Analytics and reporting
5. keitaro-optimize — Auto-optimization engine
6. keitaro-landing — Landing page generation and management
7. keitaro-audit — Campaign health audit

Output Format

All reports follow this structure:

## [Report Title]
**Period:** [date range]
**Campaigns analyzed:** [count]

### Summary
[Key findings in 2-3 bullets]

### Details
[Tables with metrics]

### Actions
- [Prioritized action items with expected impact]