19 KiB
19 KiB
Intent Research API Reference
Date: 2025-01-29
Status: Current API Documentation
📋 Overview
This document provides comprehensive API reference for intent-driven research endpoints. All endpoints require authentication via get_current_user dependency.
Base Path: /api/research
🔐 Authentication
All endpoints require authentication. The user_id is extracted from the JWT token via get_current_user dependency.
Error Response (401):
{
"detail": "Authentication required"
}
📡 Endpoints
1. POST /api/research/intent/analyze
Analyzes user input to understand research intent, generates targeted queries, and optimizes provider parameters.
Request
Endpoint: POST /api/research/intent/analyze
Headers:
Authorization: Bearer <jwt_token>
Content-Type: application/json
Body:
{
user_input: string; // Required: User's keywords, question, or goal
keywords?: string[]; // Optional: Extracted keywords
use_persona?: boolean; // Optional: Use research persona (default: true)
use_competitor_data?: boolean; // Optional: Use competitor data (default: true)
}
Example:
{
"user_input": "AI marketing tools for small businesses",
"keywords": ["AI", "marketing", "tools", "small", "businesses"],
"use_persona": true,
"use_competitor_data": true
}
Response
Success (200):
{
success: boolean; // Always true on success
intent: {
input_type: "keywords" | "question" | "goal" | "mixed";
primary_question: string;
secondary_questions: string[];
purpose: "learn" | "create_content" | "make_decision" | "compare" |
"solve_problem" | "find_data" | "explore_trends" |
"validate" | "generate_ideas";
content_output: "blog" | "podcast" | "video" | "social_post" |
"newsletter" | "presentation" | "report" |
"whitepaper" | "email" | "general";
expected_deliverables: string[]; // e.g., ["key_statistics", "expert_quotes", "case_studies"]
depth: "overview" | "detailed" | "expert";
focus_areas: string[];
perspective?: string;
time_sensitivity: "real_time" | "recent" | "historical" | "evergreen";
confidence: number; // 0.0 - 1.0
confidence_reason?: string;
great_example?: string;
needs_clarification: boolean;
clarifying_questions: string[];
analysis_summary: string;
};
analysis_summary: string;
suggested_queries: Array<{
query: string;
purpose: string; // Expected deliverable type
provider: "exa" | "tavily";
priority: number; // 1-5 (5 = highest)
expected_results: string;
justification?: string;
}>;
suggested_keywords: string[];
suggested_angles: string[];
quick_options: Array<any>; // Deprecated in unified approach
confidence_reason?: string;
great_example?: string;
optimized_config: {
provider: "exa" | "tavily" | "google";
provider_justification: string;
// Exa Settings
exa_type: "auto" | "neural" | "fast" | "deep";
exa_type_justification: string;
exa_category?: "company" | "research paper" | "news" | "github" |
"tweet" | "personal site" | "pdf" | "financial report" | "people";
exa_category_justification?: string;
exa_include_domains?: string[];
exa_include_domains_justification?: string;
exa_num_results: number;
exa_num_results_justification: string;
exa_date_filter?: string; // ISO date string
exa_date_justification?: string;
exa_highlights: boolean;
exa_highlights_justification: string;
exa_context: boolean;
exa_context_justification: string;
// Tavily Settings
tavily_topic: "general" | "news" | "finance";
tavily_topic_justification: string;
tavily_search_depth: "basic" | "advanced";
tavily_search_depth_justification: string;
tavily_include_answer: boolean | "basic" | "advanced";
tavily_include_answer_justification: string;
tavily_time_range?: "day" | "week" | "month" | "year";
tavily_time_range_justification?: string;
tavily_max_results: number;
tavily_max_results_justification: string;
tavily_raw_content: "false" | "true" | "markdown" | "text";
tavily_raw_content_justification: string;
};
recommended_provider: "exa" | "tavily" | "google";
error_message?: string; // Only present on error
}
Error (500):
{
"success": false,
"intent": {},
"analysis_summary": "",
"suggested_queries": [],
"suggested_keywords": [],
"suggested_angles": [],
"quick_options": [],
"confidence_reason": null,
"great_example": null,
"error_message": "Error message here"
}
Example Response
{
"success": true,
"intent": {
"input_type": "keywords",
"primary_question": "What are the best AI marketing tools for small businesses?",
"secondary_questions": [
"What features do small businesses need in AI marketing tools?",
"What is the ROI of AI marketing tools for small businesses?"
],
"purpose": "make_decision",
"content_output": "blog",
"expected_deliverables": ["key_statistics", "case_studies", "comparisons", "best_practices"],
"depth": "detailed",
"focus_areas": ["small business", "AI automation", "marketing efficiency"],
"time_sensitivity": "recent",
"confidence": 0.85,
"confidence_reason": "Clear intent to find tools for decision-making",
"needs_clarification": false,
"clarifying_questions": [],
"analysis_summary": "User wants to research AI marketing tools specifically for small businesses, likely to make a purchasing decision. Needs comparisons, statistics, and case studies."
},
"analysis_summary": "User wants to research AI marketing tools specifically for small businesses...",
"suggested_queries": [
{
"query": "best AI marketing tools small business 2024 comparison",
"purpose": "comparisons",
"provider": "exa",
"priority": 5,
"expected_results": "Tool comparison articles and reviews",
"justification": "High priority for decision-making"
},
{
"query": "AI marketing tools ROI statistics small business",
"purpose": "key_statistics",
"provider": "exa",
"priority": 4,
"expected_results": "Statistics on AI tool adoption and ROI",
"justification": "Important for decision-making"
}
],
"suggested_keywords": ["AI marketing", "automation", "small business", "SMB tools"],
"suggested_angles": [
"Compare top AI marketing tools for small businesses",
"ROI analysis of AI marketing automation",
"Case studies: Small businesses using AI marketing tools"
],
"optimized_config": {
"provider": "exa",
"provider_justification": "Exa's semantic search is best for finding tool comparisons and detailed analysis",
"exa_type": "neural",
"exa_type_justification": "Neural search provides better semantic understanding for tool comparisons",
"exa_category": "company",
"exa_category_justification": "Focus on company/product pages for tool information",
"exa_num_results": 10,
"exa_num_results_justification": "10 results provide comprehensive coverage without overwhelming",
"exa_highlights": true,
"exa_highlights_justification": "Highlights help extract key features and comparisons",
"exa_context": true,
"exa_context_justification": "Context string enables better AI analysis of results"
},
"recommended_provider": "exa"
}
Implementation Details
Backend Flow:
- Validates authentication
- Fetches research persona (if
use_persona: true) - Fetches competitor data (if
use_competitor_data: true) - Calls
UnifiedResearchAnalyzer.analyze() - Returns structured response
Performance: Typically 2-5 seconds (single LLM call)
2. POST /api/research/intent/research
Executes research based on confirmed intent and returns structured deliverables.
Request
Endpoint: POST /api/research/intent/research
Headers:
Authorization: Bearer <jwt_token>
Content-Type: application/json
Body:
{
user_input: string; // Required: Original user input
confirmed_intent?: ResearchIntent; // Optional: Confirmed intent from UI
selected_queries?: ResearchQuery[]; // Optional: Selected queries to execute
max_sources?: number; // Optional: Max sources (default: 10, min: 1, max: 25)
include_domains?: string[]; // Optional: Domains to include
exclude_domains?: string[]; // Optional: Domains to exclude
skip_inference?: boolean; // Optional: Skip intent inference if intent provided (default: false)
}
Example:
{
"user_input": "AI marketing tools for small businesses",
"confirmed_intent": {
"primary_question": "What are the best AI marketing tools for small businesses?",
"purpose": "make_decision",
"expected_deliverables": ["key_statistics", "case_studies", "comparisons"],
"depth": "detailed"
},
"selected_queries": [
{
"query": "best AI marketing tools small business 2024 comparison",
"purpose": "comparisons",
"provider": "exa",
"priority": 5
}
],
"max_sources": 10,
"include_domains": [],
"exclude_domains": []
}
Response
Success (200):
{
success: boolean;
// Direct Answers
primary_answer: string;
secondary_answers: Dict<string, string>;
// Deliverables
statistics: Array<{
value: string;
description: string;
citation: {
title: string;
url: string;
domain: string;
};
relevance_score: number;
}>;
expert_quotes: Array<{
quote: string;
author: string;
author_title?: string;
source: {
title: string;
url: string;
domain: string;
};
relevance_score: number;
}>;
case_studies: Array<{
title: string;
summary: string;
key_findings: string[];
source: {
title: string;
url: string;
domain: string;
};
relevance_score: number;
}>;
trends: Array<{
trend: string;
description: string;
evidence: string[];
time_frame: string;
source: {
title: string;
url: string;
domain: string;
};
}>;
comparisons: Array<{
title: string;
items: Array<{
name: string;
attributes: Dict<string, string>;
}>;
source: {
title: string;
url: string;
domain: string;
};
}>;
best_practices: string[];
step_by_step: string[];
pros_cons?: {
pros: string[];
cons: string[];
source?: {
title: string;
url: string;
domain: string;
};
};
definitions: Dict<string, string>;
examples: string[];
predictions: string[];
// Content-Ready Outputs
executive_summary: string;
key_takeaways: string[];
suggested_outline: string[];
// Sources and Metadata
sources: Array<{
title: string;
url: string;
domain: string;
snippet: string;
credibility_score: number;
relevance_score: number;
published_date?: string;
}>;
confidence: number; // 0.0 - 1.0
gaps_identified: string[];
follow_up_queries: string[];
// The inferred/confirmed intent
intent?: ResearchIntent;
error_message?: string; // Only present on error
}
Error (500):
{
"success": false,
"primary_answer": "",
"secondary_answers": {},
"statistics": [],
"expert_quotes": [],
"case_studies": [],
"trends": [],
"comparisons": [],
"best_practices": [],
"step_by_step": [],
"pros_cons": null,
"definitions": {},
"examples": [],
"predictions": [],
"executive_summary": "",
"key_takeaways": [],
"suggested_outline": [],
"sources": [],
"confidence": 0.0,
"gaps_identified": [],
"follow_up_queries": [],
"error_message": "Error message here"
}
Example Response
{
"success": true,
"primary_answer": "The best AI marketing tools for small businesses include Mailchimp, HubSpot, and Hootsuite, offering automation, analytics, and social media management at affordable prices.",
"secondary_answers": {
"pricing": "Most tools range from $0-50/month for small businesses",
"features": "Key features include email automation, social scheduling, and analytics"
},
"statistics": [
{
"value": "78%",
"description": "of small businesses use AI marketing tools",
"citation": {
"title": "Small Business Marketing Trends 2024",
"url": "https://example.com/trends",
"domain": "example.com"
},
"relevance_score": 0.95
}
],
"expert_quotes": [
{
"quote": "AI marketing tools have become essential for small businesses to compete effectively.",
"author": "Jane Smith",
"author_title": "Marketing Expert",
"source": {
"title": "Marketing Technology Guide",
"url": "https://example.com/guide",
"domain": "example.com"
},
"relevance_score": 0.90
}
],
"case_studies": [
{
"title": "Small Business Increases ROI by 40% with AI Tools",
"summary": "A local bakery used AI marketing automation to increase customer engagement and revenue.",
"key_findings": [
"40% increase in ROI",
"3x email open rates",
"50% reduction in manual work"
],
"source": {
"title": "Case Study: AI Marketing Success",
"url": "https://example.com/case-study",
"domain": "example.com"
},
"relevance_score": 0.88
}
],
"trends": [
{
"trend": "AI Marketing Automation Adoption",
"description": "Small businesses are rapidly adopting AI marketing tools",
"evidence": [
"78% adoption rate in 2024",
"Growing market of affordable tools"
],
"time_frame": "2024",
"source": {
"title": "Marketing Trends Report",
"url": "https://example.com/trends",
"domain": "example.com"
}
}
],
"comparisons": [
{
"title": "AI Marketing Tools Comparison",
"items": [
{
"name": "Mailchimp",
"attributes": {
"price": "$0-50/month",
"features": "Email, Automation, Analytics"
}
},
{
"name": "HubSpot",
"attributes": {
"price": "$0-90/month",
"features": "CRM, Email, Social, Analytics"
}
}
],
"source": {
"title": "Tool Comparison Guide",
"url": "https://example.com/comparison",
"domain": "example.com"
}
}
],
"best_practices": [
"Start with free trials to test tools",
"Focus on tools that integrate with your existing stack",
"Prioritize automation features for time savings"
],
"step_by_step": [
"1. Identify your marketing needs",
"2. Research available AI tools",
"3. Compare features and pricing",
"4. Start with free trials",
"5. Implement gradually"
],
"pros_cons": {
"pros": [
"Time savings through automation",
"Better targeting and personalization",
"Improved ROI tracking"
],
"cons": [
"Learning curve for new tools",
"Potential costs for advanced features",
"Dependency on technology"
]
},
"definitions": {
"AI Marketing": "Use of artificial intelligence to automate and optimize marketing tasks",
"Marketing Automation": "Technology that automates repetitive marketing tasks"
},
"examples": [
"Mailchimp's AI-powered email subject line suggestions",
"HubSpot's predictive lead scoring",
"Hootsuite's optimal posting time recommendations"
],
"predictions": [
"AI marketing tools will become standard for all businesses by 2026",
"Integration between tools will improve significantly",
"Costs will continue to decrease as competition increases"
],
"executive_summary": "AI marketing tools offer significant benefits for small businesses, including automation, better targeting, and improved ROI. Key tools include Mailchimp, HubSpot, and Hootsuite, with most offering affordable pricing for small businesses.",
"key_takeaways": [
"78% of small businesses use AI marketing tools",
"Tools range from $0-50/month for small businesses",
"Key benefits include automation and improved ROI",
"Free trials are available for most tools"
],
"suggested_outline": [
"Introduction to AI Marketing Tools",
"Benefits for Small Businesses",
"Top Tools Comparison",
"Case Studies and Success Stories",
"Implementation Guide",
"Conclusion and Recommendations"
],
"sources": [
{
"title": "Small Business Marketing Trends 2024",
"url": "https://example.com/trends",
"domain": "example.com",
"snippet": "78% of small businesses now use AI marketing tools...",
"credibility_score": 0.92,
"relevance_score": 0.95,
"published_date": "2024-01-15"
}
],
"confidence": 0.88,
"gaps_identified": [
"Limited data on long-term ROI",
"Need more case studies from specific industries"
],
"follow_up_queries": [
"What are the specific ROI metrics for AI marketing tools?",
"How do AI marketing tools compare to traditional methods?"
],
"intent": {
"primary_question": "What are the best AI marketing tools for small businesses?",
"purpose": "make_decision",
"expected_deliverables": ["key_statistics", "case_studies", "comparisons"],
"depth": "detailed"
}
}
Implementation Details
Backend Flow:
- Validates authentication
- Determines intent (from
confirmed_intentor infers fromuser_input) - Generates queries (from
selected_queriesor generates from intent) - Executes research via
ResearchEngine(Exa → Tavily → Google) - Analyzes results via
IntentAwareAnalyzer - Returns structured deliverables
Performance: Typically 10-30 seconds (depends on provider and query count)
🔄 Error Handling
Common Error Responses
401 Unauthorized:
{
"detail": "Authentication required"
}
500 Internal Server Error:
{
"success": false,
"error_message": "Detailed error message",
// ... other fields with empty/default values
}
Error Scenarios
- Invalid user_input: Empty or too short
- Provider unavailable: Exa/Tavily API keys not configured
- LLM failure: AI service unavailable or rate limited
- Database error: Persona/competitor data fetch failed
- Subscription limits: User exceeded subscription quota
📊 Rate Limits
- Intent Analysis: Subject to subscription tier limits
- Research Execution: Subject to subscription tier limits
- Provider APIs: Exa/Tavily/Google have their own rate limits
🔗 Related Endpoints
GET /api/research/config- Get research configuration and persona defaultsGET /api/research/providers/status- Get provider availabilityPOST /api/research/execute- Traditional synchronous research (fallback)POST /api/research/start- Traditional asynchronous research (fallback)
📚 Related Documentation
- Intent-Driven Research Guide:
INTENT_DRIVEN_RESEARCH_GUIDE.md - Architecture Rules:
.cursor/rules/researcher-architecture.mdc - Architecture Overview:
CURRENT_ARCHITECTURE_OVERVIEW.md
Status: Current API Reference - Use this for integrating with intent-driven research endpoints.