Search API

POST

/v1/search

The Search API is Cortex's flagship endpoint that provides real-time web search with AI-generated summaries and source verification. It's designed specifically for AI applications that need current, trustworthy information.

🎯 Overview

The Search API crawls the web in real-time, analyzes multiple sources, and returns a comprehensive summary with verified citations. Perfect for:

• AI Agents - Real-time reasoning capabilities
• RAG Systems - Fresh knowledge retrieval
• Chatbots - Current, factual responses
• Research Tools - Multi-source analysis

📝 Request Format

Basic Request

curl -X POST https://api.usecortex.co/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest developments in quantum computing"
  }'

Complete Request Structure

{
  "query": "artificial intelligence breakthrough 2025",
  "max_results": 8,
  "language": "en",
  "country": "global",
  "recency": "month",
  "format": "json",
  "include_sources": true,
  "include_metadata": true,
  "domain_filter": {
    "include": ["arxiv.org", "nature.com"],
    "exclude": ["wikipedia.org"]
  },
  "options": {
    "enable_cache": true,
    "timeout": 10,
    "stream": false
  }
}

📋 Parameters

Required Parameters

Parameter	Type	Description
query	string	Search query (1-500 characters)

Core Parameters

Parameter	Type	Default	Description
max_results	integer	5	Number of sources to analyze (1-20)
language	string	"auto"	Target language (en, es, fr, de, etc.)
country	string	"global"	Geographic focus (us, uk, de, jp, etc.)
recency	string	"auto"	Time filter: day, week, month, year

Format Parameters

Parameter	Type	Default	Description
format	string	"json"	Response format: json, markdown, text
include_sources	boolean	true	Include source citations
include_metadata	boolean	true	Include processing metadata
stream	boolean	false	Enable streaming responses

Advanced Filtering

Domain Filter

{
  "domain_filter": {
    "include": ["reuters.com", "bloomberg.com", "techcrunch.com"],
    "exclude": ["reddit.com", "twitter.com"]
  }
}

Content Filter

{
  "content_filter": {
    "min_word_count": 200,
    "max_age_days": 7,
    "require_date": true,
    "content_type": ["article", "news", "research"]
  }
}

Search Options

{
  "options": {
    "enable_cache": true,
    "cache_ttl": 3600,
    "timeout": 15,
    "deep_search": false,
    "verify_sources": true
  }
}

📊 Response Format

Success Response

{
  "success": true,
  "data": {
    "summary": "Recent breakthroughs in quantum computing include...",
    "sources": [
      {
        "url": "https://nature.com/articles/quantum-breakthrough",
        "title": "Major Quantum Computing Breakthrough",
        "snippet": "Scientists have achieved a significant milestone...",
        "confidence": 0.94,
        "published_date": "2025-01-08T14:30:00Z",
        "domain": "nature.com",
        "language": "en",
        "word_count": 1200,
        "content_type": "research",
        "author": "Dr. Jane Smith",
        "citations": 45
      }
    ],
    "query_analysis": {
      "intent": "research",
      "entities": ["quantum computing", "breakthrough", "2025"],
      "complexity": "medium",
      "topic_categories": ["technology", "science"]
    },
    "trust_score": 0.91,
    "content_freshness": "recent",
    "source_diversity": 0.85
  },
  "metadata": {
    "request_id": "req_8f3a2b1c9d4e5f67",
    "timestamp": "2025-01-09T10:30:00Z",
    "processing_time": 2.34,
    "sources_found": 47,
    "sources_analyzed": 8,
    "cached": false,
    "model_version": "cortex-v2.1",
    "region": "us-east"
  },
  "usage": {
    "requests_used": 46,
    "requests_remaining": 1954,
    "reset_date": "2025-02-01T00:00:00Z"
  }
}

Response Fields

Summary Object

Field	Type	Description
summary	string	AI-generated summary (150-800 words)
trust_score	float	Overall trustworthiness (0.0-1.0)
content_freshness	string	Recency indicator (fresh/recent/moderate/stale)
source_diversity	float	Source variety score (0.0-1.0)

Sources Array

Each source includes:

Field	Type	Description
url	string	Original source URL
title	string	Article/page title
snippet	string	Relevant excerpt (150-300 chars)
confidence	float	Relevance confidence (0.0-1.0)
published_date	string	Publication date (ISO 8601)
domain	string	Source domain
language	string	Content language
word_count	integer	Estimated word count
content_type	string	Content category
author	string	Author name (if available)
citations	integer	Citation count (if available)

Query Analysis

Field	Type	Description
intent	string	Query intent (research/news/factual/opinion)
entities	array	Extracted entities and keywords
complexity	string	Query complexity (simple/medium/complex)
topic_categories	array	Identified topic categories

🎨 Response Formats

JSON Format (Default)

Standard structured JSON response as shown above.

Markdown Format

curl -X POST https://api.usecortex.co/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "AI developments", "format": "markdown"}'

Response:

# Latest AI Developments

The artificial intelligence field has seen remarkable progress in 2025, with breakthroughs in large language models, autonomous systems, and ethical AI frameworks.

## Key Developments

### Large Language Models
Recent advances include improved reasoning capabilities and reduced computational requirements[^1].

### Autonomous Systems  
Self-driving technology has achieved new safety milestones with advanced perception systems[^2].

## Sources

[^1]: [Nature: AI Reasoning Breakthrough](https://nature.com/ai-reasoning) - Published Jan 8, 2025
[^2]: [MIT Tech Review: Autonomous Systems](https://technologyreview.com/autonomous) - Published Jan 7, 2025

Text Format

curl -X POST https://api.usecortex.co/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "AI developments", "format": "text"}'

Response:

Latest AI Developments

The artificial intelligence field has seen remarkable progress in 2025, with breakthroughs in large language models, autonomous systems, and ethical AI frameworks.

Large language models have achieved improved reasoning capabilities while reducing computational requirements. Autonomous systems have reached new safety milestones with advanced perception systems.

Sources:
1. Nature: AI Reasoning Breakthrough (https://nature.com/ai-reasoning)
2. MIT Tech Review: Autonomous Systems (https://technologyreview.com/autonomous)

⚡ Streaming Responses

Enable real-time streaming for long-running searches:

curl -X POST https://api.usecortex.co/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -d '{"query": "breaking news", "stream": true}'

Stream events:

event: progress
data: {"status": "searching", "sources_found": 12}

event: source
data: {"url": "https://example.com", "title": "Breaking News", "confidence": 0.89}

event: summary
data: {"text": "Recent developments include...", "confidence": 0.92}

event: complete
data: {"status": "complete", "total_time": 3.45}

🔍 Search Strategies

News & Current Events

{
  "query": "latest developments in renewable energy",
  "recency": "day",
  "max_results": 10,
  "domain_filter": {
    "include": ["reuters.com", "bloomberg.com", "bbc.com"]
  }
}

Academic Research

{
  "query": "machine learning interpretability methods",
  "domain_filter": {
    "include": ["arxiv.org", "nature.com", "acm.org"]
  },
  "content_filter": {
    "content_type": ["research", "paper"],
    "min_word_count": 500
  }
}

Technical Documentation

{
  "query": "React 18 new features best practices",
  "domain_filter": {
    "include": ["reactjs.org", "github.com", "dev.to"]
  },
  "language": "en"
}

Market Analysis

{
  "query": "Tesla stock analysis Q4 2024",
  "recency": "week",
  "domain_filter": {
    "include": ["seekingalpha.com", "morningstar.com", "fool.com"]
  },
  "max_results": 15
}

🏃 Performance Optimization

Caching

{
  "query": "weather forecast New York",
  "options": {
    "enable_cache": true,
    "cache_ttl": 1800  // 30 minutes
  }
}

Timeout Management

{
  "query": "comprehensive market analysis",
  "options": {
    "timeout": 30,      // 30 seconds max
    "deep_search": true // More thorough analysis
  }
}

Geographic Optimization

{
  "query": "local business regulations",
  "country": "de",
  "language": "en"
}

🚨 Error Handling

Common Errors

Error Code	Description	Solution
QUERY_TOO_SHORT	Query under 1 character	Provide meaningful query
QUERY_TOO_LONG	Query over 500 characters	Shorten query
MAX_RESULTS_EXCEEDED	max_results > 20	Reduce max_results
INVALID_LANGUAGE	Unsupported language code	Use ISO 639-1 codes
INVALID_COUNTRY	Unsupported country code	Use ISO 3166-1 codes
TIMEOUT_EXCEEDED	Search took too long	Reduce scope or timeout

Error Response Example

{
  "success": false,
  "error": {
    "code": "QUERY_TOO_SHORT",
    "message": "Query must be at least 1 character long",
    "details": {
      "parameter": "query",
      "provided": "",
      "minimum_length": 1,
      "maximum_length": 500
    }
  },
  "request_id": "req_error_789"
}

📊 Usage Examples

Python SDK

from cortex import CortexClient

client = CortexClient(api_key="your_key")

# Basic search
result = client.search("quantum computing breakthrough")
print(result.summary)

# Advanced search
result = client.search(
    query="AI safety research",
    max_results=10,
    recency="month",
    domain_filter={"include": ["arxiv.org", "openai.com"]}
)

for source in result.sources:
    print(f"{source.title}: {source.confidence}")

JavaScript SDK

import Cortex from '@cortex/sdk';

const cortex = new Cortex({ apiKey: 'your_key' });

// Basic search
const result = await cortex.search('quantum computing breakthrough');
console.log(result.summary);

// Streaming search
const stream = cortex.searchStream('breaking news AI');
stream.on('source', (source) => {
  console.log(`Found: ${source.title}`);
});
stream.on('complete', (result) => {
  console.log(`Summary: ${result.summary}`);
});

cURL Examples

# Basic search
curl -X POST https://api.usecortex.co/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"query": "latest AI developments"}'

# News search with filters
curl -X POST https://api.usecortex.co/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "stock market today",
    "recency": "day",
    "max_results": 8,
    "domain_filter": {
      "include": ["cnbc.com", "marketwatch.com"]
    }
  }'

💡 Best Practices

Query Optimization

✅ Effective queries:

• "latest iPhone 15 Pro review benchmarks"
• "renewable energy investment trends Q4 2024"
• "TypeScript 5.0 new features migration guide"

❌ Avoid:

• Single words: "AI", "stocks"
• Too broad: "everything about technology"
• Personal info: "John's opinion on AI"

Performance Tips

1. Use appropriate max_results (5-10 for most cases)
2. Filter by domain for specific verticals
3. Set recency filters for time-sensitive queries
4. Enable caching for repeated queries
5. Use streaming for real-time applications

Integration Patterns

# Retry logic for production
import time
from cortex import CortexClient, CortexError

def search_with_retry(query, max_retries=3):
    client = CortexClient(api_key="your_key")
    
    for attempt in range(max_retries):
        try:
            return client.search(query)
        except CortexError as e:
            if e.code == "RATE_LIMITED":
                time.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise e
    
    raise Exception("Max retries exceeded")

---

🔄 Related Endpoints

• Extract API → - URL content extraction
• Validate API → - Source verification
• Cache API → - Result caching

🆘 Need Help?

• API Explorer - Interactive testing
• Discord Community - Developer support
• Support Email - Technical assistance