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.
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