Skip to main content

​
Overview

There are two ways to access CodeAlive programmatically:
MethodBest forHow it works
MCP (recommended)AI agent integrationsYour agent connects to CodeAlive as an MCP server and uses tools like codebase_search automatically
REST APICustom integrations, scripts, CI/CDDirect HTTP requests to CodeAlive endpoints
Most users should use MCP integration — it’s simpler and handles tool discovery automatically. Use the REST API when you need direct programmatic access.

​
Authentication

All API requests require a Bearer token in the Authorization header: 
Authorization: Bearer YOUR_API_KEY
Get your API key from the CodeAlive dashboard under MCP & API → + Create API Key.
You can create an API key after adding at least one repository to your organization. You do not need to wait for indexing to finish to create the key, but search and chat calls become useful only after indexing completes.
Never commit API keys to version control. Use environment variables:
export CODEALIVE_API_KEY="your_key_here"
See the Authentication reference for details on key rotation, rate limit headers, and error responses.

​
Base URLs

EndpointURLUse case
REST APIhttps://app.codealive.ai/apiDirect API calls, scripts, CI/CD
MCP (Remote)https://mcp.codealive.ai/api/AI agent integrations
MCP (Local Docker)http://localhost:8000/apiSelf-hosted, lower latency

​
Quick Start Examples

​
1. List your data sources

Check which repositories are indexed and available: 
curl -H "Authorization: Bearer $CODEALIVE_API_KEY" \
  https://app.codealive.ai/api/datasources/all
Response: 
[
  {
    "id": "abc123",
    "name": "my-backend",
    "type": "Repository"
  },
  {
    "id": "def456",
    "name": "my-frontend",
    "type": "Repository"
  }
]
Search across your codebase by meaning, not just keywords: 
curl -X POST https://app.codealive.ai/api/search \
  -H "Authorization: Bearer $CODEALIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "user authentication middleware",
    "datasource_ids": ["abc123"]
  }'

​
3. Chat with your codebase

Ask questions and get answers with full codebase context: 
curl -X POST https://app.codealive.ai/api/chat/completions \
  -H "Authorization: Bearer $CODEALIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "role": "user",
        "content": "How does error handling work in the API layer?"
      }
    ],
    "datasource_ids": ["abc123"],
    "stream": false
  }'
Use "stream": true for streaming responses via Server-Sent Events (SSE). This is how most AI agents consume the chat API.

​
Error Handling

The API uses standard HTTP status codes:
StatusMeaningCommon cause
200SuccessRequest completed
400Bad RequestInvalid parameters, missing required fields
401UnauthorizedMissing or invalid API key
403ForbiddenValid key but insufficient permissions
404Not FoundEndpoint or resource doesn’t exist
429Rate LimitedToo many requests — back off and retry
500Server ErrorInternal issue — retry or contact support
Error response format: 
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

​
Handling rate limits

When you receive a 429 response, use exponential backoff: 
import time
import requests

def call_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)
        if response.status_code == 429:
            wait = 2 ** attempt  # 1s, 2s, 4s
            time.sleep(wait)
            continue
        return response
    return response

​
Best Practices

Search before chat

codebase_search is fast and cheap. Use it to find relevant code first, then use codebase_consultant for synthesis and analysis.

Scope your queries

Pass specific datasource_ids to limit searches to relevant repositories. Avoid searching everything when you know which repo you need.

Use conversation IDs

For multi-turn chats, pass the conversation_id from previous responses. This maintains context and produces better follow-up answers.

Cache data source lists

The list of data sources changes rarely. Cache the result of /datasources/all instead of calling it before every search.

​
Next Steps

API Reference

Full endpoint documentation

MCP Integration

Set up CodeAlive with your AI agent