Your First Request

This guide walks you through making your first Cortex API request, understanding parameters, and interpreting responses.

🎯 Basic Search Request

Let's start with a simple search:

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"
  }'

📝 Request Structure

Required Parameters

Parameter	Type	Description
`query`	string	Your search query (max 500 characters)

Optional Parameters

Parameter	Type	Default	Description
`max_results`	integer	5	Number of sources to analyze (1-20)
`include_sources`	boolean	true	Include source citations
`language`	string	"auto"	Target language (en, es, fr, de, etc.)
`recency`	string	"auto"	Filter by recency (day, week, month, year)
`domain_filter`	array	null	Include/exclude specific domains
`country`	string	"global"	Geographic focus (us, uk, de, etc.)

🔍 Advanced Request Examples

News Search with Recency Filter

{
  "query": "Tesla stock price movement",
  "max_results": 8,
  "recency": "day",
  "domain_filter": {
    "include": ["reuters.com", "bloomberg.com", "cnbc.com"]
  }
}

Research Query with Language Preference

{
  "query": "machine learning breakthrough 2025",
  "max_results": 10,
  "language": "en",
  "domain_filter": {
    "include": ["arxiv.org", "nature.com", "science.org"],
    "exclude": ["wikipedia.org"]
  }
}

Geographic-Specific Search

{
  "query": "renewable energy policies",
  "country": "de",
  "language": "en",
  "max_results": 6
}

📊 Response Structure

Here's a detailed breakdown of the response:

{
  "summary": "Quantum computing has seen significant advances...",
  "sources": [
    {
      "url": "https://example.com/quantum-breakthrough",
      "title": "Major Quantum Computing Breakthrough Announced",
      "snippet": "Scientists at MIT have developed...",
      "confidence": 0.94,
      "published_date": "2025-01-08T15:30:00Z",
      "domain": "example.com",
      "language": "en",
      "word_count": 1200
    }
  ],
  "metadata": {
    "query_time": 2.15,
    "sources_found": 47,
    "sources_analyzed": 8,
    "confidence_score": 0.91,
    "cached": false,
    "model_version": "cortex-v2.1"
  },
  "query_analysis": {
    "intent": "research",
    "entities": ["quantum computing", "developments"],
    "complexity": "medium"
  },
  "request_id": "req_8f3a2b1c9d4e5f67"
}

Response Fields Explained

Summary

Type: String
Description: AI-generated summary combining information from all sources
Length: Typically 150-500 words
Language: Matches request language preference

Sources Array

Each source object contains:

Field	Type	Description
`url`	string	Original source URL
`title`	string	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	Approximate article length

Metadata Object

Performance and quality metrics:

Field	Description
`query_time`	Total processing time (seconds)
`sources_found`	Total sources discovered
`sources_analyzed`	Sources used for summary
`confidence_score`	Overall response confidence
`cached`	Whether result was cached
`model_version`	AI model version used

🎨 Response Formats

Markdown Format

Request markdown-formatted responses:

{
  "query": "Python data science libraries",
  "format": "markdown",
  "include_citations": true
}

Response:

# Python Data Science Libraries

The Python ecosystem offers several powerful libraries for data science:

## Core Libraries
- **NumPy** - Fundamental package for numerical computing[^1]
- **Pandas** - Data manipulation and analysis[^2]
- **Matplotlib** - Comprehensive plotting library[^3]

[^1]: https://numpy.org/doc/stable/
[^2]: https://pandas.pydata.org/docs/
[^3]: https://matplotlib.org/stable/contents.html

Structured Data

For programmatic use:

{
  "query": "compare iPhone vs Samsung Galaxy specs",
  "format": "structured",
  "schema": "comparison"
}

⚡ Performance Optimization

Caching

Cortex automatically caches frequent queries:

{
  "query": "daily weather forecast New York",
  "cache_ttl": 3600  // Cache for 1 hour
}

Streaming Responses

For real-time applications:

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}'

🚨 Error Handling

Common Errors

Status Code	Error	Description
`400`	Bad Request	Invalid query parameters
`401`	Unauthorized	Invalid API key
`429`	Rate Limited	Too many requests
`500`	Server Error	Internal processing error

Error Response Format

{
  "error": {
    "code": "INVALID_QUERY",
    "message": "Query parameter is required",
    "details": {
      "parameter": "query",
      "provided": null,
      "expected": "string (1-500 characters)"
    }
  },
  "request_id": "req_error_123"
}

Retry Logic

Implement exponential backoff:

import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def make_request_with_retry(query):
    session = requests.Session()
    
    retry_strategy = Retry(
        total=3,
        backoff_factor=1,
        status_forcelist=[429, 500, 502, 503, 504],
    )
    
    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", adapter)
    
    response = session.post(
        "https://api.usecortex.co/v1/search",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        json={"query": query}
    )
    
    return response.json()

📈 Testing Your Integration

Health Check

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.usecortex.co/v1/health

Rate Limit Check

curl -I -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.usecortex.co/v1/search

Response headers include:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

💡 Best Practices

Query Optimization

✅ Good queries:

"latest iPhone 15 reviews and specifications"
"renewable energy investment trends 2025"
"machine learning papers published this month"

❌ Avoid:

Single words: "AI"
Too broad: "everything about technology"
Too specific: "John Smith from 123 Main St opinions"

Efficient Usage

Cache results for repeated queries
Use appropriate max_results (5-10 for most cases)
Filter domains for specific use cases
Set reasonable timeouts (5-10 seconds)

🔄 Next Steps

Now that you've made your first request:

Explore API Reference → - Full API documentation
Try SDKs → - Python and JavaScript libraries
Integration Guides → - Common use cases

🆘 Troubleshooting

Slow responses?

Reduce max_results
Use domain filtering
Check your internet connection

Low quality results?

Make queries more specific
Use domain filtering for authoritative sources
Try different query phrasings

Need help?

Check API status
Join our Discord
Email help@usecortex.co

Next: API Overview → - Deep dive into all available endpoints

🎯 Basic Search Request​

📝 Request Structure​

Required Parameters​

Optional Parameters​

🔍 Advanced Request Examples​

News Search with Recency Filter​

Research Query with Language Preference​

Geographic-Specific Search​

📊 Response Structure​

Response Fields Explained​

Summary​

Sources Array​

Metadata Object​

🎨 Response Formats​

Markdown Format​

Structured Data​

⚡ Performance Optimization​

Caching​

Streaming Responses​

🚨 Error Handling​

Common Errors​

Error Response Format​

Retry Logic​

📈 Testing Your Integration​

Health Check​

Rate Limit Check​

💡 Best Practices​

Query Optimization​

Efficient Usage​

🔄 Next Steps​

🆘 Troubleshooting​