Skip to main content

API Overview

Cortex provides a comprehensive REST API that serves as the trust layer between AI systems and the open web. This overview covers all available endpoints, authentication, and core concepts.

🔗 Base URL​

All API requests are made to:

https://api.usecortex.co/v1/

🔑 Authentication​

All requests require authentication via API key:

Authorization: Bearer cortex_sk_your_api_key_here

Alternative header:

X-API-Key: cortex_sk_your_api_key_here

📋 Available Endpoints​

Core Search & Extraction​

EndpointMethodDescription
/searchPOSTReal-time web search with AI summaries
/extractPOSTClean text extraction from URLs
/summarizePOSTAI-powered content summarization

Trust & Validation Layer​

EndpointMethodDescription
/validatePOSTCross-source fact verification
/cache/queryGETRetrieve cached trusted results
/cache/storePOSTStore results in trust cache

Monitoring & Analytics​

EndpointMethodDescription
/usageGETAPI usage statistics
/healthGETService health status
/auditGETRequest audit trail

🌐 Request Format​

All requests use JSON format:

Content-Type: application/json

Standard Request Structure​

{
  "query": "your search query",
  "options": {
    "max_results": 5,
    "language": "en",
    "format": "json"
  },
  "metadata": {
    "request_id": "optional_custom_id",
    "user_id": "optional_user_identifier"
  }
}

📊 Response Format​

All responses follow a consistent structure:

{
  "success": true,
  "data": {
    // Endpoint-specific data
  },
  "metadata": {
    "request_id": "req_123abc",
    "timestamp": "2025-01-09T10:30:00Z",
    "processing_time": 1.23,
    "version": "v1.0"
  },
  "usage": {
    "requests_used": 45,
    "requests_remaining": 1955
  }
}

Error Response Format​

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

🚦 Rate Limits​

Rate limits vary by plan:

PlanRequests/MinuteRequests/MonthBurst Limit
Free1010020
Starter602,000100
Pro30010,000500
EnterpriseCustomCustomCustom

Rate Limit Headers​

Responses include rate limiting information:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1640995200
X-RateLimit-Burst: 100

🌍 Regions & Availability​

Cortex is available in multiple regions:

RegionEndpointLocation
US Easthttps://us-east.api.usecortex.co/v1/Virginia
US Westhttps://us-west.api.usecortex.co/v1/California
Europehttps://eu.api.usecortex.co/v1/Ireland
Asia Pacifichttps://ap.api.usecortex.co/v1/Singapore
Regional Selection

Use the region closest to your users for optimal performance. The main endpoint automatically routes to the nearest region.

📈 Status Codes​

CodeStatusDescription
200OKRequest successful
400Bad RequestInvalid request parameters
401UnauthorizedInvalid or missing API key
403ForbiddenInsufficient permissions
429Too Many RequestsRate limit exceeded
500Internal Server ErrorServer processing error
502Bad GatewayTemporary service issue
503Service UnavailableMaintenance mode

🔍 Search Parameters​

Common parameters across search endpoints:

Query Parameters​

ParameterTypeDefaultDescription
querystringrequiredSearch query (1-500 chars)
max_resultsinteger5Sources to analyze (1-20)
languagestring"auto"Target language code
countrystring"global"Geographic focus
recencystring"auto"Time filter (day/week/month/year)

Response Format Options​

ParameterTypeDefaultDescription
formatstring"json"Response format (json/markdown/text)
include_sourcesbooleantrueInclude source citations
include_metadatabooleantrueInclude processing metadata
streambooleanfalseEnable streaming responses

Filtering Options​

{
  "domain_filter": {
    "include": ["reuters.com", "bloomberg.com"],
    "exclude": ["example.com"]
  },
  "content_filter": {
    "min_word_count": 100,
    "max_age_days": 30,
    "require_date": true
  }
}

🔒 Security Features​

Request Validation​

  • Query sanitization - Removes potential injection attempts
  • Parameter validation - Strict type and range checking
  • Rate limiting - Prevents abuse and ensures fair usage
  • IP filtering - Optional IP whitelisting (Enterprise)

Response Safety​

  • Content filtering - Removes malicious or inappropriate content
  • Source verification - Validates source authenticity
  • Injection protection - Sanitizes all output content
  • Safe rendering - Prevents XSS and code injection

📊 Monitoring & Analytics​

Request Tracking​

Every request includes:

  • Unique request ID for debugging
  • Processing time metrics
  • Source quality scores
  • Cache hit/miss status

Usage Analytics​

Access detailed usage statistics:

  • Requests per day/month
  • Success/error rates
  • Average response times
  • Popular query patterns

🧪 Testing Environment​

Use our sandbox environment for development:

https://sandbox.api.usecortex.co/v1/

Features:

  • Free unlimited requests
  • Mock responses for consistent testing
  • No rate limits during development
  • Same API interface as production

🔄 Versioning​

Cortex uses URL-based versioning:

  • Current: v1 (stable)
  • Beta: v2-beta (preview features)
  • Deprecated: v0 (legacy, remove by Q3 2025)

Version headers:

API-Version: v1
Accept-Version: v1

📚 OpenAPI Specification​

Download our complete OpenAPI specification:

🆘 Support & Resources​

🚀 Quick Start Links​

Ready to start building? Choose an endpoint to dive deeper!