Skip to main content
GET
/
api
/
search
Search
curl --request GET \
  --url https://api.example.com/api/search
{
  "results": [
    {
      "kind": "<string>",
      "dataSource": {
        "id": "<string>",
        "name": "<string>",
        "type": "<string>"
      },
      "identifier": "<string>",
      "location": {
        "path": "<string>",
        "range": {
          "start": {
            "line": 123,
            "character": 123
          },
          "end": {
            "line": 123,
            "character": 123
          }
        }
      },
      "score": 123,
      "description": "<string>",
      "contentByteSize": 123,
      "snippet": "<string>",
      "content": "<string>"
    }
  ]
}

​
Overview

The Search endpoint provides semantic search capabilities across your indexed repositories and workspaces. It intelligently searches through code, finding relevant results based on the meaning of your query, not just keyword matching.

​
Request

​
Query Parameters

​
Query
string
required
The search query string. Describes what you’re looking for in natural language or keywords.
​
DataSourceIds
array
Array of data source IDs to search within. If omitted, searches across all available data sources.
​
Names
array
Alternative to DataSourceIds — array of data source names to search within. You can also pass workspace names here to search across all repositories in a workspace.
​
Mode
string
Search mode to use. Options:
  • Auto (default): Automatically selects the best mode
  • Fast: Quick search with good results
  • FastComplex: Fast search optimized for complex queries
  • Deep: Thorough search with more comprehensive results
​
IncludeContent
boolean
default:"false"
Whether to include the full content of search results. Set to true to get the actual code content. Note: MCP server and Skills always use IncludeContent=false — use the /api/search/artifacts endpoint to fetch content separately.
​
DescriptionDetail
string
default:"Short"
Level of detail for result descriptions. Options:
  • Short (default): Brief summary of each result
  • Full: More detailed description of each result

​
Response

​
results
array
Array of search result objects

​
Code Examples

import requests

url = "https://app.codealive.ai/api/search"
headers = {
    "Authorization": "Bearer YOUR_API_KEY"
}

# Search within specific data sources by name
params = {
    "Query": "user authentication flow",
    "Names": ["MyApiProject", "PaymentService"],
    "Mode": "Auto",
    "IncludeContent": True
}

response = requests.get(url, headers=headers, params=params)
results = response.json()

for result in results['results']:
    print(f"Found {result['kind']} in {result['location']['path']}")
    print(f"  Score: {result['score']}")
    print(f"  Snippet: {result['snippet'][:100]}...")

​
Search by Data Source

You can limit search to specific repositories or workspaces: 
params = {
    "Query": "payment processing",
    "Names": ["MyApiProject", "PaymentService"]
}

response = requests.get(
    "https://app.codealive.ai/api/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params=params
)
You can pass workspace names into the Names parameter to search across all repositories within that workspace.

​
Example Response

{
  "results": [
    {
      "kind": "class",
      "dataSource": {
        "id": "60d21b4667d0d63ce0f9a1d1",
        "name": "MyApiProject",
        "type": "Repository"
      },
      "identifier": "UserAuthService",
      "location": {
        "path": "src/services/AuthService.cs",
        "range": {
          "start": {
            "line": 15,
            "character": 4
          },
          "end": {
            "line": 120,
            "character": 5
          }
        }
      },
      "score": 0.95,
      "description": "Main authentication service implementing IAuthService with token generation and credential validation",
      "contentByteSize": 4250,
      "snippet": "public class UserAuthService : IAuthService\n{\n    private readonly ITokenGenerator _tokenGenerator;",
      "content": "// Full class content here (if IncludeContent=true)"
    },
    {
      "kind": "function",
      "dataSource": {
        "id": "60d21b4667d0d63ce0f9a1d1",
        "name": "MyApiProject",
        "type": "Repository"
      },
      "identifier": "ValidateCredentials",
      "location": {
        "path": "src/services/AuthService.cs",
        "range": {
          "start": {
            "line": 45,
            "character": 8
          },
          "end": {
            "line": 68,
            "character": 9
          }
        }
      },
      "score": 0.87,
      "description": "Validates user credentials against the identity store",
      "contentByteSize": 890,
      "snippet": "public async Task<bool> ValidateCredentials(string username, string password)"
    }
  ]
}

​
Search Modes

Automatically selects the best search strategy based on your query complexity: 
params = {"Query": "how does user login work", "Mode": "Auto"}

​
Fast Mode

Quick results for simple queries: 
params = {"Query": "AuthService", "Mode": "Fast"}

​
Fast Complex Mode

Optimized for complex queries while maintaining speed: 
params = {"Query": "authentication with JWT tokens and refresh mechanism", "Mode": "FastComplex"}

​
Deep Mode

Comprehensive search with more thorough analysis: 
params = {"Query": "security vulnerabilities in payment flow", "Mode": "Deep"}

​
Use Cases

​
Finding Implementation Details

# Find how a specific feature is implemented
response = requests.get(
    "https://app.codealive.ai/api/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "Query": "email notification implementation",
        "Mode": "Deep",
        "IncludeContent": True
    }
)

​
Code Review Assistance

# Search for similar patterns across the codebase
response = requests.get(
    "https://app.codealive.ai/api/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "Query": "error handling patterns",
        "Mode": "Auto"
    }
)

​
Security Audit

# Find potential security issues
response = requests.get(
    "https://app.codealive.ai/api/search",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    params={
        "Query": "SQL query construction user input",
        "Mode": "Deep"
    }
)

​
Error Responses

​
400 Bad Request

{
  "message": "Query parameter is required",
  "details": "The Query parameter must be provided"
}

​
401 Unauthorized

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

​
500 Internal Server Error

{
  "message": "Search failed",
  "details": "An error occurred while processing the search query"
}

​
Best Practices

  • Use Fast mode for simple identifier lookups
  • Use Deep mode only when you need comprehensive results
  • Specify data sources to narrow search scope
  • Set IncludeContent=false when you only need locations
  • Use natural language to describe what you’re looking for
  • Be specific about the context (e.g., “JWT authentication” vs “authentication”)
  • Include relevant technical terms and concepts
  • For complex queries, use Deep or FastComplex mode
  • Sort results by score to prioritize most relevant matches
  • Use snippet for quick overview before loading full content
  • Combine with Chat API for deeper analysis of results
For best performance, use a two-step approach:
  1. Search with IncludeContent=false to get file paths, descriptions, and identifiers
  2. Fetch content only for relevant results using POST /api/search/artifacts
This avoids transferring large amounts of code you may not need. Use DescriptionDetail=Full to get richer descriptions that help you decide which artifacts to fetch.MCP server and Skills always use this pattern — they never send IncludeContent=true.