API Reference - Momentize.ai

Base URL

https://api.momentize.ai

Authentication

All API requests require an API key. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Get your API key by signing up for an account.

POST /v1/analyze

Analyzes a conversation to detect high-value moments and returns relevant sponsored content blocks.

Request Body

Field	Type	Required
conversation	Array	Yes
session_id	String	Yes
user_context	Object	No

Example Request

{
  "conversation": [
    {
      "role": "user",
      "content": "I'm looking to buy a new smartphone",
      "timestamp": "2024-01-20T10:30:00Z"
    },
    {
      "role": "assistant", 
      "content": "I can help you find the perfect smartphone. What's your budget range?"
    }
  ],
  "session_id": "unique-session-identifier",
  "user_context": {
    "location": "US",
    "preferences": ["technology", "reviews"]
  }
}

Response

Example Response

{
  "session_id": "unique-session-identifier",
  "moments_detected": [
    {
      "moment_type": "purchase_intent",
      "confidence": 0.92,
      "estimated_value": 3.50,
      "keywords_matched": ["buy", "looking"],
      "context": "I'm looking to buy a new smartphone"
    }
  ],
  "sponsored_content": [
    {
      "impression_id": "imp_abc123",
      "advertiser_id": "tech_store_1",
      "advertiser_name": "TechHub Electronics",
      "content_type": "text",
      "title": "Latest Smartphones Available",
      "description": "Find the perfect smartphone with free shipping...",
      "cta_text": "Shop Now",
      "cta_url": "https://techhub.example.com/phones",
      "image_url": "https://techhub.example.com/images/phone-hero.jpg",
      "disclosure": "Sponsored Content"
    }
  ],
  "total_estimated_value": 3.50
}

Moment Types

purchase_intent - User expressing intent to buy something
comparison - User comparing products or services
problem - User reporting an issue or problem
how_to - User asking for instructions or tutorials
booking - User wanting to schedule or reserve something
location_need - User looking for local businesses or services
budget_discussed - User mentioning budget or pricing

POST /v1/events

Track user interactions with sponsored content blocks for analytics and billing.

Request Body

Field	Type	Required
event_type	String	Yes
session_id	String	Yes
impression_id	String	No
advertiser_id	String	No
metadata	Object	No

Example Request

{
  "event_type": "click",
  "session_id": "unique-session-identifier",
  "impression_id": "imp_abc123",
  "advertiser_id": "tech_store_1",
  "metadata": {
    "click_position": "cta_button",
    "user_agent": "Chrome/120.0.0.0",
    "referrer": "https://example.com"
  }
}

Response

Example Response

{
  "success": true,
  "event_id": 12345
}

Event Types

impression - Sponsored content block was displayed to user
click - User clicked on sponsored content block
conversion - User completed a desired action (purchase, signup, etc.)

GET /v1/stats

Get analytics data including moment counts, click-through rates, revenue, and top advertisers.

Response

Example Response

{
  "total_moments": 1542,
  "moments_by_type": {
    "purchase_intent": 421,
    "comparison": 312,
    "problem": 298,
    "how_to": 189,
    "booking": 156,
    "location_need": 98,
    "budget_discussed": 68
  },
  "total_impressions": 892,
  "total_clicks": 134,
  "click_through_rate": 15.02,
  "total_revenue": 2847.50,
  "top_advertisers": [
    {
      "advertiser_id": "tech_store_1",
      "name": "TechHub Electronics",
      "impressions": 245,
      "category": "electronics"
    }
  ],
  "recent_moments": [
    {
      "id": 1542,
      "session_id": "session-xyz",
      "moment_type": "purchase_intent",
      "confidence": 0.87,
      "estimated_value": 2.10,
      "keywords_matched": ["buy", "need"],
      "created_at": "2024-01-20T15:30:45Z"
    }
  ]
}

Rate Limits

Free Tier

1,000 requests/month

Pro Tier

100,000 requests/month

Enterprise

Custom limits

Error Codes

Code	Description
400	Bad Request - Invalid request format
401	Unauthorized - Invalid or missing API key
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Something went wrong