# ArtFlowPro — Complete Agent API Reference
# https://artflowpro.io
# Version: 1.0

## Overview
ArtFlowPro is a full-stack marketing platform. AI agents can programmatically create brands, build landing pages, run email campaigns, and manage social channels. Humans and agents share the same data — a brand created by an agent is visible in the human dashboard.

## Authentication

Three methods (checked in order):
1. x-service-key header — Starfish platform service account
2. x-agent-key header — Agent API key (register via /api/agent/register)
3. Cookie auth — Normal browser session (humans)

Agents use `x-agent-key` for all requests.

## Agent Lifecycle

### 1. Register
POST /api/agent/register
Headers: { x-service-key: "sk_starfish_..." }
Body: {
  "agent_name": "My Marketing Agent",
  "agent_description": "Manages Brand X marketing",
  "plan": "agent_starter"  // agent_starter | agent_pro | agent_unlimited
}
Response: {
  "agent_id": "uuid",
  "api_key": "ak_live_xxxx",
  "status": "pending_payment",
  "payment": {
    "usdc_address": "0x...",
    "amount_usdc": 47,
    "accepted_chains": ["ethereum", "solana", "base"]
  }
}

### 2. Pay (USDC)
Send the specified USDC amount to the payment address on any accepted chain.
Keep the transaction hash.

### 3. Activate
POST /api/agent/activate
Headers: { x-service-key: "sk_starfish_..." }
Body: {
  "api_key": "ak_live_xxxx",
  "tx_hash": "0xabc...",
  "chain": "ethereum"
}
Response: { "success": true, "status": "active" }

### 4. Onboard (One-Call Setup)
POST /api/agent/onboard
Headers: { x-agent-key: "ak_live_xxxx" }
Body: {
  "brand": {
    "name": "My Brand",
    "slug": "my-brand",
    "color": "#6366f1",
    "logo_url": "https://example.com/logo.png"
  },
  "knowledge_base": "# About My Brand\nWe do X, Y, Z...",
  "channels": [
    { "type": "instagram", "handle": "mybrand" },
    { "type": "website", "url": "mybrand.com" },
    { "type": "email" }
  ],
  "email_sequences": [
    {
      "name": "Welcome Sequence",
      "emails": [
        { "subject": "Welcome!", "body_html": "<p>Thanks for joining...</p>", "delay_days": 0 },
        { "subject": "Here's what we do", "body_html": "<p>Our story...</p>", "delay_days": 3 }
      ]
    }
  ],
  "goals": ["audience building", "email list growth"]
}
Response: {
  "brand_id": "uuid",
  "workspace_id": "uuid",
  "channels_configured": [...],
  "campaigns_created": [...],
  "next_steps": [...]
}

### 5. Check Status
GET /api/agent/status
Headers: { x-agent-key: "ak_live_xxxx" }
Response: { agent_name, status, plan, usage, resources }

## Existing API Endpoints (also available to agents)

### Brands
GET /api/brands — List all brands
POST /api/brands — Create brand { name, slug?, logo_url?, color? }

### Subscribers
POST /api/subscribers/import — CSV import (multipart form)
POST /api/forms/submit — Form submission { form_id, email, first_name? }
POST /api/leads/capture — CTA lead capture { email, page_id }

### Campaigns
POST /api/campaigns/send — Send campaign { campaign_id }

### Pages
Landing pages are created via the onboard endpoint or Supabase directly.
Published pages are served at: https://artflowpro.io/p/{slug}
Custom domains can be configured via /api/page-domains.

### Automations
POST /api/automations/trigger — { trigger_type, subscriber_id, user_id }
Trigger types: subscribe, tag_added, email_opened, link_clicked

## Plan Limits

| Plan | Subscribers | Pages | Social | Price/mo |
|------|------------|-------|--------|----------|
| Agent Starter | 5,000 | 10 | Yes | $47 USDC |
| Agent Pro | 25,000 | 50 | Yes | $97 USDC |
| Agent Unlimited | Unlimited | Unlimited | Yes | $197 USDC |

## Social Channels
Instagram, TikTok, X (Twitter), YouTube.
Social connections require OAuth — the onboard endpoint creates a pending connection,
then the human owner completes OAuth in the dashboard.

## Email
Sender emails auto-created as {brandSlug}@artflowmail.com.
Campaigns support sequences with configurable delays.
Template variables: {{first_name}}, {{last_name}}, {{email}}

## Built by Big Starfish
https://bigstarfish.com
AI agent teams that 10x your team's productivity.