Authenticated API

This endpoint requires a valid JWT Bearer token. Accessible via the API gateway at /v1/ai/*.

Minerva Marketing API

AI-powered marketing orchestration platform for campaigns, multi-channel messaging, and attribution.

Overview

Attribute	Value
Base Path	`/api/v1/minerva`
Authentication	Bearer Token
Required Roles	JWT authentication required (no specific role restriction)

Campaigns

List Campaigns

Retrieve marketing campaigns.

GET /api/v1/minerva/campaigns

Query Parameters

Parameter	Type	Description
`status`	string	`draft`, `active`, `paused`, `completed`
`type`	string	Campaign type filter
`channel`	string	`sms`, `email`, `push`, `all`
`start_date`	date	Filter by start date
`page`	integer	Page number

Response

{
  "data": [
    {
      "id": "camp_001",
      "name": "Summer Promo 2026",
      "type": "promotional",
      "status": "active",
      "channels": ["sms", "email", "push"],
      "audience": {
        "segment_id": "seg_001",
        "segment_name": "Active Customers",
        "size": 5420
      },
      "schedule": {
        "start_date": "2026-06-01T00:00:00Z",
        "end_date": "2026-08-31T23:59:59Z",
        "timezone": "America/Los_Angeles"
      },
      "metrics": {
        "sent": 5420,
        "delivered": 5380,
        "opened": 2150,
        "clicked": 845,
        "converted": 156,
        "revenue_attributed": 4680.00
      },
      "created_at": "2026-05-15T10:00:00Z"
    }
  ]
}

Campaign Types

Type	Description
`promotional`	Promotional offers
`onboarding`	Welcome series
`reengagement`	Win-back campaigns
`transactional`	Order notifications
`loyalty`	Loyalty communications
`event`	Event-triggered
`ai_generated`	AI-recommended

Create Campaign

POST /api/v1/minerva/campaigns

Request Body

{
  "name": "Flash Sale Friday",
  "type": "promotional",
  "channels": ["sms", "push"],
  "segment_id": "seg_001",
  "content": {
    "sms": {
      "message": "🔥 Flash Sale! 25% off today only. Use code FLASH25. Order: {{order_link}}"
    },
    "push": {
      "title": "Flash Sale Alert!",
      "body": "25% off today only - don't miss out!",
      "image_url": "https://...",
      "action_url": "olympus://order?promo=FLASH25"
    }
  },
  "schedule": {
    "type": "immediate",
    "send_time": null
  },
  "settings": {
    "promo_code": "FLASH25",
    "discount_percent": 25,
    "track_conversions": true,
    "attribution_window_days": 7
  }
}

Get Campaign

GET /api/v1/minerva/campaigns/{campaign_id}

Response

{
  "id": "camp_001",
  "name": "Flash Sale Friday",
  "type": "promotional",
  "status": "active",
  "channels": ["sms", "push"],
  "audience": {
    "segment_id": "seg_001",
    "segment_name": "Active Customers",
    "size": 5420,
    "criteria": {
      "last_order_days_ago": {"lte": 30}
    }
  },
  "content": {...},
  "metrics": {
    "by_channel": {
      "sms": {
        "sent": 5420,
        "delivered": 5380,
        "clicked": 620,
        "cost": 270.00
      },
      "push": {
        "sent": 4200,
        "delivered": 4150,
        "clicked": 380,
        "cost": 0
      }
    },
    "conversions": {
      "total": 156,
      "revenue": 4680.00,
      "avg_order_value": 30.00,
      "roi": 1633.3
    }
  },
  "timeline": [
    {"event": "created", "timestamp": "2026-01-24T10:00:00Z"},
    {"event": "activated", "timestamp": "2026-01-24T12:00:00Z"},
    {"event": "first_conversion", "timestamp": "2026-01-24T12:15:00Z"}
  ]
}

Update Campaign

PUT /api/v1/minerva/campaigns/{campaign_id}

Pause Campaign

POST /api/v1/minerva/campaigns/{campaign_id}/pause

Resume Campaign

POST /api/v1/minerva/campaigns/{campaign_id}/resume

Delete Campaign

DELETE /api/v1/minerva/campaigns/{campaign_id}

SMS Messaging

Send SMS

Send individual or bulk SMS messages.

POST /api/v1/minerva/sms/send

Request Body

{
  "to": "+1234567890",
  "message": "Your order #42 is ready for pickup!",
  "type": "transactional",
  "metadata": {
    "order_id": "ord_xyz",
    "customer_id": "cust_abc"
  }
}

Response

{
  "message_id": "sms_001",
  "status": "queued",
  "to": "+1234567890",
  "segments": 1,
  "cost": 0.05,
  "queued_at": "2026-01-24T19:00:00Z"
}

Send Bulk SMS

POST /api/v1/minerva/sms/bulk

Request Body

{
  "segment_id": "seg_001",
  "message": "Happy Hour starts at 4pm! 🍺 Show this text for 20% off drinks.",
  "schedule": {
    "send_at": "2026-01-24T15:30:00Z",
    "timezone": "America/Los_Angeles"
  }
}

Get SMS Status

GET /api/v1/minerva/sms/{message_id}

Response

{
  "message_id": "sms_001",
  "status": "delivered",
  "to": "+1234567890",
  "delivered_at": "2026-01-24T19:00:05Z",
  "events": [
    {"event": "queued", "timestamp": "2026-01-24T19:00:00Z"},
    {"event": "sent", "timestamp": "2026-01-24T19:00:02Z"},
    {"event": "delivered", "timestamp": "2026-01-24T19:00:05Z"}
  ]
}

SMS Status Values

Status	Description
`queued`	In send queue
`sent`	Sent to carrier
`delivered`	Delivered to phone
`failed`	Delivery failed
`undelivered`	Could not deliver

Email Marketing

Send Email

POST /api/v1/minerva/email/send

Request Body

{
  "to": "customer@example.com",
  "template_id": "template_order_confirm",
  "subject": "Your Order #42 is Confirmed!",
  "variables": {
    "customer_name": "John",
    "order_number": "42",
    "items": [...],
    "total": 45.99
  },
  "type": "transactional"
}

Send Campaign Email

POST /api/v1/minerva/email/campaign

Request Body

{
  "campaign_id": "camp_001",
  "segment_id": "seg_001",
  "template_id": "template_promo",
  "subject": "🔥 Exclusive Offer Inside",
  "preview_text": "25% off your next order...",
  "schedule": {
    "send_at": "2026-01-25T10:00:00Z",
    "timezone": "America/Los_Angeles"
  },
  "settings": {
    "track_opens": true,
    "track_clicks": true,
    "unsubscribe_group_id": "grp_promo"
  }
}

List Email Templates

GET /api/v1/minerva/email/templates

Response

{
  "data": [
    {
      "id": "template_001",
      "name": "Order Confirmation",
      "type": "transactional",
      "subject_default": "Your Order #{{order_number}} is Confirmed",
      "variables": ["customer_name", "order_number", "items", "total"],
      "preview_url": "https://...",
      "updated_at": "2026-01-20T10:00:00Z"
    }
  ]
}

Create Email Template

POST /api/v1/minerva/email/templates

Request Body

{
  "name": "Weekly Newsletter",
  "type": "marketing",
  "subject": "This Week at {{restaurant_name}}",
  "html_content": "<html>...",
  "text_content": "Plain text version...",
  "variables": ["restaurant_name", "featured_item", "promo_code"]
}

Push Notifications

Send Push

POST /api/v1/minerva/push/send

Request Body

{
  "customer_id": "cust_abc",
  "title": "Your order is ready!",
  "body": "Order #42 is ready for pickup at the counter.",
  "data": {
    "type": "order_ready",
    "order_id": "ord_xyz"
  },
  "action_url": "olympus://orders/ord_xyz"
}

Send Topic Push

Send to all subscribers of a topic.

POST /api/v1/minerva/push/topic

Request Body

{
  "topic": "daily_specials",
  "title": "Today's Special",
  "body": "Ribeye Steak - $24.99 (normally $34.99)",
  "image_url": "https://...",
  "schedule": {
    "send_at": "2026-01-24T11:00:00Z"
  }
}

Conversations

List Conversations

Get customer conversation history.

GET /api/v1/minerva/conversations

Query Parameters

Parameter	Type	Description
`customer_id`	string	Filter by customer
`channel`	string	`sms`, `email`, `chat`
`status`	string	`open`, `closed`

Response

{
  "data": [
    {
      "id": "conv_001",
      "customer_id": "cust_abc",
      "customer_name": "John Doe",
      "channel": "sms",
      "status": "open",
      "last_message": {
        "direction": "inbound",
        "content": "What time do you close tonight?",
        "timestamp": "2026-01-24T18:30:00Z"
      },
      "unread_count": 1,
      "assigned_to": null
    }
  ]
}

Get Conversation

GET /api/v1/minerva/conversations/{conversation_id}

Response

{
  "id": "conv_001",
  "customer": {
    "id": "cust_abc",
    "name": "John Doe",
    "phone": "+1234567890",
    "email": "john@example.com"
  },
  "channel": "sms",
  "messages": [
    {
      "id": "msg_001",
      "direction": "inbound",
      "content": "What time do you close tonight?",
      "timestamp": "2026-01-24T18:30:00Z"
    },
    {
      "id": "msg_002",
      "direction": "outbound",
      "content": "Hi John! We're open until 10pm tonight. See you soon!",
      "timestamp": "2026-01-24T18:31:00Z",
      "sent_by": "ai"
    }
  ]
}

Reply to Conversation

POST /api/v1/minerva/conversations/{conversation_id}/reply

Request Body

{
  "message": "We're open until 10pm tonight!",
  "use_ai": false
}

Attribution

Get Attribution Report

GET /api/v1/minerva/attribution

Query Parameters

Parameter	Type	Description
`start_date`	date	Report start
`end_date`	date	Report end
`model`	string	`first_touch`, `last_touch`, `linear`, `time_decay`

Response

{
  "period": {
    "start": "2026-01-01",
    "end": "2026-01-24"
  },
  "model": "last_touch",
  "summary": {
    "total_conversions": 1250,
    "total_revenue": 45000.00,
    "attributed_revenue": 38500.00
  },
  "by_channel": [
    {
      "channel": "sms",
      "conversions": 450,
      "revenue": 15500.00,
      "cost": 225.00,
      "roas": 68.9
    },
    {
      "channel": "email",
      "conversions": 380,
      "revenue": 12800.00,
      "cost": 50.00,
      "roas": 256.0
    },
    {
      "channel": "push",
      "conversions": 280,
      "revenue": 8200.00,
      "cost": 0,
      "roas": "∞"
    }
  ],
  "by_campaign": [
    {
      "campaign_id": "camp_001",
      "name": "Summer Promo",
      "conversions": 156,
      "revenue": 4680.00
    }
  ]
}

Get Touchpoints

GET /api/v1/minerva/attribution/touchpoints

Query Parameters

Parameter	Type	Description
`customer_id`	string	Customer ID
`conversion_id`	string	Conversion event ID

Response

{
  "conversion": {
    "id": "conv_evt_001",
    "type": "order",
    "value": 45.00,
    "timestamp": "2026-01-24T19:00:00Z"
  },
  "touchpoints": [
    {
      "channel": "email",
      "campaign": "Weekly Newsletter",
      "timestamp": "2026-01-22T10:00:00Z",
      "attribution_credit": 0.2
    },
    {
      "channel": "sms",
      "campaign": "Flash Sale",
      "timestamp": "2026-01-24T12:00:00Z",
      "attribution_credit": 0.8
    }
  ]
}

AI Recommendations

Get Recommended Campaigns

GET /api/v1/minerva/ai/recommendations

Response

{
  "recommendations": [
    {
      "type": "reengagement",
      "title": "Win Back Dormant Customers",
      "description": "245 customers haven't ordered in 30+ days",
      "audience_size": 245,
      "suggested_offer": "20% off",
      "predicted_response_rate": 0.12,
      "predicted_revenue": 1500.00,
      "confidence": 0.85
    },
    {
      "type": "upsell",
      "title": "Appetizer Add-On Campaign",
      "description": "Target customers who never order appetizers",
      "audience_size": 850,
      "suggested_offer": "Free appetizer with entree",
      "predicted_response_rate": 0.08,
      "predicted_revenue": 2800.00
    }
  ]
}

Generate AI Content

POST /api/v1/minerva/ai/generate

Request Body

{
  "type": "sms",
  "campaign_type": "promotional",
  "tone": "friendly",
  "offer": "25% off dinner",
  "constraints": {
    "max_characters": 160,
    "include_emoji": true
  }
}

Response

{
  "suggestions": [
    {
      "content": "🍽️ Craving something delicious? Get 25% off dinner tonight! Use code DINNER25 at checkout. Order now: {{link}}",
      "character_count": 142
    },
    {
      "content": "Hey foodie! 25% off dinner is calling your name 📣 Code: DINNER25. Don't miss out! {{link}}",
      "character_count": 108
    }
  ]
}

Webhooks

Event	Description
`minerva.sms_delivered`	SMS delivered
`minerva.sms_failed`	SMS delivery failed
`minerva.email_opened`	Email opened
`minerva.email_clicked`	Email link clicked
`minerva.conversion`	Attribution conversion
`minerva.unsubscribe`	Customer unsubscribed
`minerva.inbound_sms`	Customer sent SMS

Error Responses

Status	Code	Description
400	`invalid_phone`	Phone number invalid
400	`template_not_found`	Template ID invalid
403	`unsubscribed`	Customer opted out
429	`rate_limited`	Sending rate exceeded
503	`provider_error`	SMS/Email provider error

Minerva AI Guide - Platform overview
Minerva Sales Guide - Sales workflows
ACP AI Router - AI cost optimization

Overview​

Campaigns​

List Campaigns​

Campaign Types​

Create Campaign​

Get Campaign​

Update Campaign​

Pause Campaign​

Resume Campaign​

Delete Campaign​

SMS Messaging​

Send SMS​

Send Bulk SMS​

Get SMS Status​

SMS Status Values​

Email Marketing​

Send Email​

Send Campaign Email​

List Email Templates​

Create Email Template​

Push Notifications​

Send Push​

Send Topic Push​

Conversations​

List Conversations​

Get Conversation​

Reply to Conversation​

Attribution​

Get Attribution Report​

Get Touchpoints​

AI Recommendations​

Get Recommended Campaigns​

Generate AI Content​

Webhooks​

Error Responses​

Related Documentation​

Overview

Campaigns

List Campaigns

Campaign Types

Create Campaign

Get Campaign

Update Campaign

Pause Campaign

Resume Campaign

Delete Campaign

SMS Messaging

Send SMS

Send Bulk SMS

Get SMS Status

SMS Status Values

Email Marketing

Send Email

Send Campaign Email

List Email Templates

Create Email Template

Push Notifications

Send Push

Send Topic Push

Conversations

List Conversations

Get Conversation

Reply to Conversation

Attribution

Get Attribution Report

Get Touchpoints

AI Recommendations

Get Recommended Campaigns

Generate AI Content

Webhooks

Error Responses

Related Documentation