Cache API

GET

/v1/cache/query

POST

/v1/cache/store

DELETE

/v1/cache/clear

The Cache API manages Cortex's intelligent caching system for storing trusted search results, validated facts, and frequently accessed content.

🎯 Overview

Cortex's cache system provides:

Intelligent caching - Automatic result storage and retrieval
TTL management - Time-based cache expiration
Trust persistence - Verified results storage
Performance optimization - Faster response times

📋 Cache Query

GET
`/v1/cache/query`

Retrieve cached results for a query or URL.

curl -X GET "https://api.usecortex.co/v1/cache/query?q=artificial%20intelligence%20trends" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Description
`q`	string	Search query to check cache for
`url`	string	Specific URL to check cache for
`max_age`	integer	Maximum age in seconds (default: 3600)
`include_expired`	boolean	Include expired cache entries

Response

{
  "success": true,
  "data": {
    "cache_hit": true,
    "query": "artificial intelligence trends",
    "results": {
      "summary": "AI trends include advances in LLMs, autonomous systems...",
      "sources": [...],
      "trust_score": 0.92
    },
    "cache_metadata": {
      "cached_at": "2025-01-09T10:00:00Z",
      "expires_at": "2025-01-09T11:00:00Z",
      "ttl_remaining": 2847,
      "hit_count": 15,
      "last_validated": "2025-01-09T10:30:00Z"
    }
  }
}

💾 Cache Storage

POST
`/v1/cache/store`

Store search results or validated content in cache.

curl -X POST https://api.usecortex.co/v1/cache/store \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest AI developments",
    "content": {...},
    "ttl": 3600,
    "trust_level": "high"
  }'

Request Parameters

Parameter	Type	Default	Description
`query`	string	required	Search query identifier
`content`	object	required	Content to cache
`ttl`	integer	`3600`	Time to live in seconds
`trust_level`	string	`medium`	Trust level: low, medium, high
`tags`	array	`[]`	Cache tags for organization
`validation_score`	float	`null`	Validation confidence score

Request Example

{
  "query": "iPhone 15 specifications",
  "content": {
    "summary": "iPhone 15 features USB-C, 48MP camera...",
    "sources": [
      {
        "url": "https://apple.com/iphone-15",
        "title": "iPhone 15 Technical Specifications",
        "confidence": 0.98
      }
    ],
    "metadata": {
      "query_time": 2.3,
      "sources_analyzed": 5
    }
  },
  "ttl": 7200,
  "trust_level": "high",
  "tags": ["apple", "iphone", "specifications"],
  "validation_score": 0.95
}

🗑️ Cache Management

DELETE
`/v1/cache/clear`

Clear cache entries by query, tag, or time range.

curl -X DELETE https://api.usecortex.co/v1/cache/clear \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "specific query to clear",
    "tags": ["outdated"],
    "older_than": "2025-01-08T00:00:00Z"
  }'

Clear Parameters

Parameter	Type	Description
`query`	string	Specific query to clear
`tags`	array	Clear entries with these tags
`older_than`	string	Clear entries older than timestamp
`trust_level`	string	Clear entries below trust level
`force`	boolean	Force clear even if not expired

📊 Cache Statistics

GET
`/v1/cache/stats`

Get cache performance and usage statistics.

curl -X GET https://api.usecortex.co/v1/cache/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "cache_performance": {
      "hit_rate": 0.78,
      "miss_rate": 0.22,
      "total_requests": 1250,
      "cache_hits": 975,
      "cache_misses": 275
    },
    "storage_stats": {
      "total_entries": 3420,
      "storage_used": "145.7 MB",
      "storage_limit": "1 GB",
      "oldest_entry": "2025-01-01T10:00:00Z",
      "newest_entry": "2025-01-09T15:30:00Z"
    },
    "trust_distribution": {
      "high": 1256,
      "medium": 1890,
      "low": 274
    },
    "popular_queries": [
      {
        "query": "AI news today",
        "hit_count": 45,
        "last_hit": "2025-01-09T15:25:00Z"
      }
    ]
  }
}

⚡ Cache Strategies

Automatic Caching

Cortex automatically caches:

Search results with high confidence scores
Validated facts from trusted sources
Popular queries based on usage patterns
Extracted content from reliable domains

Smart TTL Management

Cache TTL is automatically adjusted based on:

Content Type	Default TTL	Factors
News	1 hour	Recency, source authority
Facts	24 hours	Validation score, consensus
Research	7 days	Publication date, citations
Reference	30 days	Stability, source quality

Cache Invalidation

Caches are automatically invalidated when:

Source content changes significantly
New contradictory evidence is found
TTL expires naturally
Trust score drops below threshold

🏷️ Cache Tags

Organize cached content with tags:

{
  "query": "Tesla Q4 earnings 2024",
  "content": {...},
  "tags": [
    "finance",
    "tesla", 
    "earnings",
    "q4-2024",
    "automotive"
  ]
}

Common Tag Categories

Category	Examples
Domain	finance, technology, health, science
Company	tesla, apple, microsoft, google
Time	q1-2024, december-2024, 2024
Type	news, research, facts, opinion
Geography	us, global, europe, asia

🔍 Cache Querying

Query Cache by Tags

curl -X GET "https://api.usecortex.co/v1/cache/query?tags=finance,tesla" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Cache by Time Range

curl -X GET "https://api.usecortex.co/v1/cache/query?after=2025-01-08T00:00:00Z&before=2025-01-09T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Complex Cache Queries

{
  "filters": {
    "tags": ["technology", "AI"],
    "trust_level": "high",
    "min_validation_score": 0.8,
    "max_age_hours": 24
  },
  "sort": "trust_score",
  "limit": 50
}

🛡️ Cache Security

Access Control

API Key Authentication - All cache operations require valid API key
User Isolation - Cache entries are isolated per API key
Rate Limiting - Cache operations count toward API limits
Audit Logging - All cache operations are logged

Data Privacy

Automatic Encryption - All cached data is encrypted at rest
Retention Limits - Data automatically purged after 90 days
Compliance - GDPR and CCPA compliant data handling
Anonymization - Personal data is automatically scrubbed

💡 Best Practices

Efficient Cache Usage

from cortex import CortexClient

client = CortexClient(api_key="your_key")

# Check cache before searching
cache_result = client.cache.query("AI developments today")

if cache_result.cache_hit and cache_result.ttl_remaining > 300:
    # Use cached result if fresh (>5 minutes remaining)
    return cache_result.results
else:
    # Perform new search and cache result
    search_result = client.search("AI developments today")
    
    client.cache.store(
        query="AI developments today",
        content=search_result,
        ttl=3600,  # 1 hour
        trust_level="high" if search_result.confidence > 0.8 else "medium"
    )
    
    return search_result

Cache Warming

Pre-populate cache with frequently needed content:

# Warm cache with common queries
common_queries = [
    "daily tech news",
    "stock market today", 
    "weather forecast",
    "trending topics"
]

for query in common_queries:
    result = client.search(query)
    client.cache.store(
        query=query,
        content=result,
        ttl=1800,  # 30 minutes
        tags=["warming", "common"]
    )

Cache Maintenance

Regular cache cleanup:

# Clear old, low-trust entries
client.cache.clear(
    trust_level="low",
    older_than="2025-01-07T00:00:00Z"
)

# Clear by tags
client.cache.clear(tags=["temporary", "test"])

# Get performance stats
stats = client.cache.stats()
if stats.hit_rate < 0.5:
    print("Consider adjusting cache strategy")

📈 Performance Impact

Cache Benefits

Metric	Improvement
Response Time	80-95% faster
API Usage	60-80% reduction
Bandwidth	70-90% savings
Cost	50-75% lower

Cache Overhead

Operation	Overhead
Cache Check	~50ms
Cache Store	~100ms
Cache Clear	~200ms

Next: Monitoring API → - Usage analytics and monitoring

🎯 Overview​

📋 Cache Query​

GET /v1/cache/query​

Query Parameters​

Response​

💾 Cache Storage​

POST /v1/cache/store​

Request Parameters​

Request Example​

🗑️ Cache Management​

DELETE /v1/cache/clear​

Clear Parameters​

📊 Cache Statistics​

GET /v1/cache/stats​

Response​

⚡ Cache Strategies​

Automatic Caching​

Smart TTL Management​

Cache Invalidation​

🏷️ Cache Tags​

Common Tag Categories​

🔍 Cache Querying​

Query Cache by Tags​

Query Cache by Time Range​

Complex Cache Queries​

🛡️ Cache Security​

Access Control​

Data Privacy​

💡 Best Practices​

Efficient Cache Usage​

Cache Warming​

Cache Maintenance​

📈 Performance Impact​

Cache Benefits​

Cache Overhead​

🎯 Overview

📋 Cache Query

GET
`/v1/cache/query`

Query Parameters

Response

💾 Cache Storage

POST
`/v1/cache/store`

Request Parameters

Request Example

🗑️ Cache Management

DELETE
`/v1/cache/clear`

Clear Parameters

📊 Cache Statistics

GET
`/v1/cache/stats`

Response

⚡ Cache Strategies

Automatic Caching

Smart TTL Management

Cache Invalidation

🏷️ Cache Tags

Common Tag Categories

🔍 Cache Querying

Query Cache by Tags

Query Cache by Time Range

Complex Cache Queries

🛡️ Cache Security

Access Control

Data Privacy

💡 Best Practices

Efficient Cache Usage

Cache Warming

Cache Maintenance

📈 Performance Impact

Cache Benefits

Cache Overhead