Skip to content

API.md

Latest commit

 

History

History
325 lines (237 loc) · 5.34 KB

API.md

File metadata and controls

325 lines (237 loc) · 5.34 KB

API Reference

HTTP Server

Start the server:

codeindex serve [path] [options]

Options

Option Default Description
--port, -p 3131 Server port
--host 127.0.0.1 Server host
--api-key - Require API key for endpoints
--cors * CORS origin
--rate-limit 120 Requests per minute per IP

Example

codeindex serve . --port 3131 --host 0.0.0.0 --api-key my-secret-key

REST Endpoints

POST /query

Query the index for relevant context.

Request

{
  "query": "How does authentication work?",
  "maxTokens": 3000,
  "maxSymbols": 10
}
Field Type Default Description
query string required Search query
maxTokens number 3000 Max tokens in response
maxSymbols number 10 Max symbols to include

Response

{
  "query": "How does authentication work?",
  "estimatedTokens": 1450,
  "traversalPath": ["root-descend [mod:src]", "modules: [mod:auth]", "selected: [file:src/auth/auth.service.ts]"],
  "files": [
    {
      "path": "src/auth/auth.service.ts",
      "symbols": ["AuthService", "login", "refreshToken"]
    }
  ],
  "context": "=== src/auth/auth.service.ts ===\nclass AuthService {\n  async login(credentials) { ... }\n}"
}

With API Key

curl -X POST http://localhost:3131/query \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{"query": "How does authentication work?"}'

POST /update

Trigger an incremental index update.

Request

{
  "force": false
}
Field Type Default Description
force boolean false Force full rebuild

Response

{
  "upToDate": false,
  "filesUpdated": 3,
  "filesNew": 1,
  "filesDeleted": 0,
  "durationMs": 2340
}

With API Key

curl -X POST http://localhost:3131/update \
  -H "X-API-Key: your-api-key"

GET /status

Get index health and statistics.

Response

{
  "exists": true,
  "projectName": "my-project",
  "totalFiles": 142,
  "totalSymbols": 892,
  "builtAt": 1699000000000,
  "isStale": false,
  "staleFiles": []
}

GET /health

Server health check.

Response

{
  "status": "ok",
  "uptime": 3600,
  "version": "0.1.0"
}

Configuration File

.codeindex.json

Project-level configuration.

{
  "provider": "openai",
  "model": "gpt-4o",
  "indexDir": ".index",
  "projectName": "my-project",
  "serverApiKey": "optional-api-key",
  "serverCorsOrigin": "*",
  "serverMaxBodyBytes": 1048576,
  "serverRateLimitPerMinute": 120
}

~/.codeindex/config.json

Global configuration (created by codeindex setup).

{
  "provider": "openai",
  "model": "gpt-4o",
  "apiKey": "sk-...",
  "baseURL": "https://api.openai.com/v1"
}

Environment Variables

Variable Description
OPENAI_API_KEY OpenAI API key
ANTHROPIC_API_KEY Anthropic API key
GOOGLE_API_KEY Google AI API key
CODEINDEX_PROVIDER Override default provider
CODEINDEX_MODEL Override default model
CODEINDEX_API_KEY Override API key

TypeScript API

IndexManager

import { IndexManager } from "@codeindex/core"

const manager = new IndexManager({
  projectRoot: "/path/to/project",
  projectName: "my-project",
  llmClient: openAiClient,
  adapters: [typescriptAdapter, pythonAdapter],
  indexDir: ".index",
  verbose: false
})

// Build index
const buildResult = await manager.build()

// Incremental update
const updateResult = await manager.update()

// Watch for changes
manager.watch({
  debounceMs: 500,
  onBatch: (changes) => console.log(changes)
})

TreeTraversal

import { TreeTraversal } from "@codeindex/core"

const traversal = new TreeTraversal({
  tree,
  llmClient,
  maxTokens: 3000,
  maxSymbols: 10
})

const result = await traversal.traverse("How does auth work?")

CLI Reference

codeindex setup

Interactive global configuration.

codeindex setup

codeindex init

Initialize project in current directory.

codeindex init [path]

codeindex index

Build or rebuild index.

codeindex index [path] [options]
Option Description
--verbose, -v Verbose output
--force Force rebuild

codeindex query

Query the index.

codeindex query "<text>" [options]
Option Description
--cwd Project directory
--format Output format (text or json)
--max-tokens Max tokens
--verbose Show traversal path

codeindex update

Incremental update.

codeindex update [path] [options]
Option Description
--force Force full rebuild

codeindex status

Check index health.

codeindex status [path]

codeindex serve

Start HTTP server.

codeindex serve [path] [options]
Option Default Description
--port, -p 3131 Port
--host 127.0.0.1 Host
--api-key - Require API key
--cors * CORS origin
--rate-limit 120 Rate limit