keitaro-flows

Keitaro Flow Management

Process

1. Read keitaro/references/keitaro-api.md for stream endpoint details
2. Read keitaro/references/flow-patterns.md for common patterns
3. Parse user intent and context
4. Execute API calls
5. Display result

Create Flow

When user describes a flow setup:

1. Identify the pattern (see references/flow-patterns.md):
   • White + Offer (cloaking)
   • A/B test
   • GEO split
   • Device split
   • Direct offer
2. Determine required fields:
   • Campaign ID (required)
   • Type: regular, forced, or default
   • Schema: redirect, landings, offers, or landings_offers
   • Weight (for A/B testing)
   • Filters (geo, device, OS, etc.)
   • Landing page IDs
   • Offer IDs
3. Create via API

Quick Patterns

"Add white page to campaign 12": Endpoint: POST /streams (NOT PUT — Keitaro uses POST for both create and update)

{
  "campaign_id": 12,
  "type": "default",
  "name": "White Page",
  "action_type": "show_landing_page",
  "schema": "landings",
  "landings": [{"id": <white_landing_id>}]
}

"Add offer flow for DE desktop": Endpoint: POST /streams

{
  "campaign_id": 12,
  "type": "regular",
  "name": "DE Desktop",
  "action_type": "redirect",
  "weight": 100,
  "schema": "landings_offers",
  "filters": [
    {"name": "geo", "mode": "accept", "payload": "DE"},
    {"name": "device_type", "mode": "accept", "payload": "desktop"}
  ],
  "landings": [{"id": 5}, {"id": 6}],
  "offers": [{"id": 10}]
}

Update stream weight: Endpoint: POST /streams/{id} (NOT PUT!)

{
  "weight": 70
}

Update Weights

When user says "change weights" or "rebalance":

1. List current flows with weights
2. Show current distribution
3. Apply new weights
4. Confirm changes

Example: "set flow A to 70% and flow B to 30%"

Configure Filters

Supported filters (from API):

• geo — country codes
• region, city — location
• device_type — desktop, mobile, tablet
• os — Windows, macOS, iOS, Android
• browser — Chrome, Firefox, Safari
• language — browser language
• connection_type — wifi, cellular
• ip — IP ranges
• referrer — referrer URL pattern
• sub_id_1 through sub_id_15 — sub-ID values

A/B Test Setup

When user says "A/B test landings in campaign 12":

1. Get current campaign flows
2. Create separate flows with equal weights
3. Assign different landings to each flow
4. Confirm setup with summary:

A/B Test Created:
├── Flow A: landing_v1.html (50% weight)
├── Flow B: landing_v2.html (50% weight)
└── Min. data needed: 100 clicks per variant

Cloaking Setup

When user says "setup cloaking for campaign 12":

1. Create default flow with white page
2. Create regular flow(s) with:
   • GEO filter (target countries)
   • Referrer filter (traffic source domain)
   • Device filter if needed
3. Assign offer landings to regular flows
4. Show complete setup summary

Flow Health Check

Quick checks for a campaign's flows:

• Any flows with 0 clicks in 24h? → "Not receiving traffic"
• Any flows with weight 0? → "Effectively disabled"
• Default flow missing? → "No white page, risky for paid traffic"
• Filters contradicting each other? → "Conflicting filters"