API Reference - Context Search

Base URL

Production: https://contextsearch.dev/api

Local Development: http://localhost:8082/api

Authentication

All API requests require authentication via API key in the X-API-Key header.

Example Request:

curl -H "X-API-Key: cs_live_your_api_key_here" \
     https://contextsearch.dev/api/search?q=authentication

Get your API key from the Dashboard → Settings → API Keys

Health & Status

GET /health

Health check endpoint (no authentication required).

Response Example:

{
  "status": "healthy",
  "timestamp": "2026-06-02T13:00:00.000000",
  "checks": {
    "database": "healthy",
    "celery": "healthy (1 workers)",
    "openai": "healthy (key configured)",
    "disk": "healthy (60% used)"
  }
}

Search

GET /api/search

Semantic code search across indexed repositories.

Query Parameters:

q (string, required)
Search query text

limit (integer, optional, default: 10)
Maximum number of results (max: 50)

repo_id (string, optional)
Filter by specific repository ID

Response Example:

{
  "results": [
    {
      "name": "authenticate_user",
      "file": "auth/handler.py",
      "line": 45,
      "code": "def authenticate_user(username, password):",
      "similarity": 0.94,
      "repo": "github:acme/backend",
      "language": "python"
    }
  ],
  "count": 1,
  "tokens_used": 257,
  "tokens_saved": 1400000
}

Analytics

GET /api/analytics/patterns

Get design pattern distribution across repositories.

Query Parameters:

repo_id (string, optional)
Filter by repository

Response Example:

{
  "patterns": {
    "singleton": 15,
    "factory": 8,
    "observer": 3
  },
  "by_language": {
    "python": {
      "singleton": 10,
      "factory": 5
    }
  },
  "total_symbols_with_patterns": 26
}

GET /api/analytics/patterns/{pattern_name}

Get all instances of a specific design pattern.

Path Parameters:

pattern_name (string, required)
Pattern: singleton, factory, observer, strategy, decorator

Query Parameters:

min_confidence (float, optional, default: 0.0)
Minimum confidence score (0.0-1.0)

limit (integer, optional, default: 50)
Maximum results

GET /api/analytics/similarity

Find similar/duplicate code across repositories.

Query Parameters:

min_similarity (float, optional, default: 0.85)
Minimum similarity score (0.0-1.0)

limit (integer, optional, default: 20)
Maximum clusters

Response Example:

{
  "clusters": [
    {
      "similarity": 0.92,
      "size": 3,
      "symbols": [
        {
          "name": "parse_config",
          "file": "utils/config.py",
          "repo": "github:acme/api"
        },
        {
          "name": "parse_settings",
          "file": "core/settings.py",
          "repo": "github:acme/frontend"
        }
      ]
    }
  ],
  "total_clusters": 5
}

GET /api/analytics/quality

Code quality metrics across repositories.

Response Example:

{
  "total_symbols": 1247,
  "avg_lines_of_code": 42,
  "pattern_coverage": 0.28,
  "by_repo": [
    {
      "repo_id": "repo-123",
      "name": "github:acme/api",
      "symbols": 523,
      "avg_loc": 38,
      "patterns": 145
    }
  ]
}

Repositories

GET /api/repos

List all indexed repositories.

Response Example:

{
  "repos": [
    {
      "id": "repo-123",
      "name": "acme/backend",
      "provider": "github",
      "indexed_at": "2026-06-01T10:30:00Z",
      "symbols_count": 523,
      "status": "indexed"
    }
  ],
  "total": 1
}

POST /api/repos/index

Request indexing of a new repository.

Request Body:

{
  "provider": "github",
  "repo_name": "username/repository",
  "branch": "main"
}

Rate Limits

Beta accounts are limited to:

100 searches per day
10 repository indexing requests per month
1 concurrent indexing job

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1717344000

Error Responses

401 Unauthorized:

{
  "error": "Invalid or missing API key"
}

429 Too Many Requests:

{
  "error": "Rate limit exceeded",
  "retry_after": 3600
}

500 Internal Server Error:

{
  "error": "Internal server error",
  "request_id": "req_abc123"
}

Support

Need help? Contact us:

Dashboard: Manage your account
Issues: Report bugs via dashboard
Response time: <24 hours for beta customers