API Reference

CKB HTTP API

REST API for Code Knowledge Backend (CKB) providing codebase comprehension capabilities with background job support, CI/CD integration, and runtime telemetry.

Quick Start

# Start the server (default: localhost:8080)
./ckb serve

# Start on custom port
./ckb serve --port 8081

# Start on custom host
./ckb serve --host 0.0.0.0 --port 8080

API Endpoints

System & Health

`GET /`

Root endpoint with API information and available endpoints.

curl http://localhost:8080/

`GET /health`

Simple liveness check for load balancers.

curl http://localhost:8080/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-12-16T12:00:00Z",
  "version": "0.1.0"
}

`GET /health/detailed` (v7.3)

Detailed health status with per-repository metrics, storage info, and memory usage.

curl http://localhost:8080/health/detailed

Response:

{
  "status": "healthy",
  "timestamp": "2024-12-22T12:00:00Z",
  "version": "7.3.0",
  "uptime": "2h15m30s",
  "repos": {
    "my-project": {
      "status": "healthy",
      "symbolCount": 4520,
      "refCount": 18500,
      "lastIndexed": "2024-12-22T10:00:00Z",
      "indexAgeMinutes": 120
    }
  },
  "storage": {
    "databaseSize": 52428800,
    "snapshotCount": 3,
    "oldestSnapshot": "2024-12-20T12:00:00Z"
  },
  "journal": {
    "entryCount": 1250,
    "oldestEntry": "2024-12-21T08:00:00Z",
    "pendingCompaction": false
  },
  "memory": {
    "allocBytes": 104857600,
    "heapInUse": 83886080,
    "goroutines": 24
  },
  "backends": {
    "scip": {"available": true, "latencyMs": 5},
    "lsp": {"available": true, "latencyMs": 12},
    "git": {"available": true, "latencyMs": 2}
  }
}

`GET /ready`

Readiness check that verifies backend availability.

curl http://localhost:8080/ready

Response:

{
  "status": "ready",
  "timestamp": "2024-12-16T12:00:00Z",
  "backends": {
    "scip": true,
    "lsp": true,
    "git": true
  }
}

`GET /status`

Comprehensive system status including repository, backends, cache, and index freshness (v7.2).

curl http://localhost:8080/status

Response:

{
  "status": "ready",
  "timestamp": "2024-12-18T12:00:00Z",
  "repository": {
    "root": "/path/to/repo",
    "name": "my-project"
  },
  "backends": {
    "scip": true,
    "lsp": true,
    "git": true
  },
  "index": {
    "status": "fresh",
    "lastIndexed": "2024-12-18T10:00:00Z",
    "ageMinutes": 120,
    "stale": false,
    "reason": "indexed within freshness window"
  },
  "tier": {
    "current": "standard",
    "available": ["fast", "standard"],
    "missing": ["telemetry"]
  }
}

Diagnostics

`GET /doctor`

Run diagnostic checks on all system components.

Query Parameters (v7.2):

tier - Check requirements for specific tier: "fast", "standard", or "full"

# Run all diagnostics
curl http://localhost:8080/doctor

# Check requirements for standard tier
curl "http://localhost:8080/doctor?tier=standard"

# Check requirements for full tier (with telemetry)
curl "http://localhost:8080/doctor?tier=full"

Response:

{
  "status": "healthy",
  "timestamp": "2024-12-18T12:00:00Z",
  "tier": "standard",
  "checks": [
    {"name": "config", "status": "pass", "message": "Configuration is valid"},
    {"name": "scip", "status": "pass", "message": "SCIP index found and fresh"},
    {"name": "tree-sitter", "status": "pass", "message": "Tree-sitter available for 8 languages"}
  ],
  "issues": [],
  "summary": {
    "total": 5,
    "passed": 5,
    "warnings": 0,
    "failed": 0
  },
  "tierRequirements": {
    "fast": {"met": true, "requires": ["tree-sitter"]},
    "standard": {"met": true, "requires": ["scip-index"]},
    "full": {"met": false, "requires": ["telemetry"], "missing": ["telemetry"]}
  }
}

`POST /doctor/fix`

Get a fix script for detected issues.

curl -X POST http://localhost:8080/doctor/fix

Indexing (v7.1/v7.2)

`POST /index`

Trigger SCIP index generation. Auto-detects language and runs the appropriate indexer.

Request Body:

{
  "force": false,
  "language": "auto"
}

Parameters:

force - Re-index even if index is fresh (default: false)
language - Override auto-detection: "go", "typescript", "python", "rust", "java", "kotlin", "cpp", "dart", "ruby", "csharp", "php" (default: "auto")

# Auto-detect and index (skips if fresh)
curl -X POST http://localhost:8080/index

# Force re-index
curl -X POST http://localhost:8080/index \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

# Index specific language
curl -X POST http://localhost:8080/index \
  -H "Content-Type: application/json" \
  -d '{"language": "go"}'

Response:

{
  "status": "completed",
  "language": "go",
  "indexer": "scip-go",
  "duration": "12.5s",
  "symbolCount": 4520,
  "fileCount": 156,
  "indexPath": ".scip/index.scip",
  "timestamp": "2024-12-18T12:00:00Z"
}

Response (skipped - already fresh):

{
  "status": "skipped",
  "reason": "index is fresh",
  "lastIndexed": "2024-12-18T10:00:00Z",
  "ageMinutes": 45,
  "freshnessThreshold": 60,
  "hint": "Use force=true to re-index anyway",
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /index/status`

Get current index status and freshness information.

curl http://localhost:8080/index/status

Response:

{
  "exists": true,
  "path": ".scip/index.scip",
  "language": "go",
  "lastIndexed": "2024-12-18T10:00:00Z",
  "ageMinutes": 120,
  "fresh": true,
  "freshnessThreshold": 180,
  "symbolCount": 4520,
  "fileCount": 156,
  "locked": false,
  "timestamp": "2024-12-18T12:00:00Z"
}

Delta Ingestion (v7.3)

Delta artifacts enable O(delta) server-side ingestion. See Incremental-Indexing for details.

`GET /delta`

Get delta ingestion status and info.

curl http://localhost:8080/delta

Response:

{
  "enabled": true,
  "schemaVersion": 1,
  "activeSnapshotId": "sha256:abc123...",
  "lastDeltaIngested": "2024-12-22T10:00:00Z",
  "pendingDeltas": 0,
  "timestamp": "2024-12-22T12:00:00Z"
}

`POST /delta/validate`

Validate a delta artifact without applying it.

Request Body: Delta JSON (see Incremental-Indexing#Delta JSON Schema)

curl -X POST http://localhost:8080/delta/validate \
  -H "Content-Type: application/json" \
  -d @delta.json

Response (valid):

{
  "valid": true,
  "schemaVersion": 1,
  "baseSnapshotMatch": true,
  "stats": {
    "symbolsAdded": 15,
    "symbolsModified": 8,
    "symbolsDeleted": 3,
    "refsAdded": 42,
    "refsDeleted": 12
  },
  "timestamp": "2024-12-22T12:00:00Z"
}

Response (invalid):

{
  "valid": false,
  "errors": [
    "base_snapshot_id mismatch: expected sha256:abc123, got sha256:def456",
    "stats count mismatch: claimed 15 added, found 14"
  ],
  "timestamp": "2024-12-22T12:00:00Z"
}

`POST /delta/ingest`

Ingest a delta artifact to incrementally update the index.

Request Body: Delta JSON (see Incremental-Indexing#Delta JSON Schema)

curl -X POST http://localhost:8080/delta/ingest \
  -H "Content-Type: application/json" \
  -d @delta.json

Response:

{
  "status": "success",
  "applied": {
    "symbolsAdded": 15,
    "symbolsModified": 8,
    "symbolsDeleted": 3,
    "refsAdded": 42,
    "refsDeleted": 12,
    "callEdgesAdded": 27,
    "callEdgesDeleted": 5
  },
  "newSnapshotId": "sha256:def456...",
  "duration": "45ms",
  "timestamp": "2024-12-22T12:00:00Z"
}

Prometheus Metrics (v7.3)

`GET /metrics`

Prometheus-format metrics for monitoring and alerting.

curl http://localhost:8080/metrics

Response:

# HELP ckb_ingestion_total Total ingestion operations
# TYPE ckb_ingestion_total counter
ckb_ingestion_total{repo="my-project",type="delta"} 42
ckb_ingestion_total{repo="my-project",type="full"} 3

# HELP ckb_ingestion_duration_seconds Ingestion duration histogram
# TYPE ckb_ingestion_duration_seconds histogram
ckb_ingestion_duration_seconds_bucket{repo="my-project",type="delta",le="0.1"} 38
ckb_ingestion_duration_seconds_bucket{repo="my-project",type="delta",le="1"} 42
ckb_ingestion_duration_seconds_sum{repo="my-project",type="delta"} 2.5
ckb_ingestion_duration_seconds_count{repo="my-project",type="delta"} 42

# HELP ckb_search_total Total search operations
# TYPE ckb_search_total counter
ckb_search_total{repo="my-project",type="fts5"} 1250

# HELP ckb_storage_bytes Storage usage in bytes
# TYPE ckb_storage_bytes gauge
ckb_storage_bytes{repo="my-project",type="database"} 52428800
ckb_storage_bytes{repo="my-project",type="snapshots"} 157286400

# HELP ckb_symbols_total Total symbol count
# TYPE ckb_symbols_total gauge
ckb_symbols_total{repo="my-project"} 4520

# HELP ckb_goroutines Current goroutine count
# TYPE ckb_goroutines gauge
ckb_goroutines 24

# HELP ckb_memory_alloc_bytes Memory allocated in bytes
# TYPE ckb_memory_alloc_bytes gauge
ckb_memory_alloc_bytes 104857600

# HELP ckb_uptime_seconds Server uptime in seconds
# TYPE ckb_uptime_seconds counter
ckb_uptime_seconds 8130

Language Quality (v7.3)

Quality assessment endpoints for language support tiers.

`GET /meta/languages`

Get language quality dashboard with tier information and metrics.

curl http://localhost:8080/meta/languages

Response:

{
  "timestamp": "2024-12-22T12:00:00Z",
  "primaryLanguage": "go",
  "overallQuality": "ok",
  "totalSymbols": 4520,
  "totalRefs": 18500,
  "totalCallEdges": 2800,
  "summary": "All languages indexed with good quality",
  "languages": {
    "go": {
      "displayName": "Go",
      "tier": 1,
      "tierName": "Tier 1 (Full)",
      "quality": "ok",
      "symbolCount": 4520,
      "refCount": 18500,
      "callEdgeCount": 2800,
      "fileCount": 156,
      "refAccuracy": 0.98,
      "callGraphQuality": "ok",
      "knownIssues": [],
      "recommendations": []
    }
  }
}

`GET /meta/python-env`

Detect Python virtual environment status and provide recommendations.

curl http://localhost:8080/meta/python-env

Response:

{
  "timestamp": "2024-12-22T12:00:00Z",
  "activeVenv": "",
  "isActive": false,
  "detectedVenvs": [".venv", "venv"],
  "hasPyproject": true,
  "hasRequirements": true,
  "hasPipfile": false,
  "recommendation": "Activate virtual environment before running 'ckb index' for best results: source .venv/bin/activate"
}

`GET /meta/typescript-monorepo`

Detect TypeScript monorepo configuration and workspace type.

curl http://localhost:8080/meta/typescript-monorepo

Response:

{
  "timestamp": "2024-12-22T12:00:00Z",
  "isMonorepo": true,
  "workspaceType": "pnpm",
  "hasRootTsconfig": true,
  "packages": ["pkg-a", "pkg-b", "pkg-c"],
  "packagesWithTsconfig": ["pkg-a", "pkg-b"],
  "recommendation": "Add tsconfig.json to packages for better type resolution. Use scip-typescript --infer-tsconfig for monorepos."
}

Symbol Operations

`GET /symbol/:id`

Retrieve detailed information about a symbol.

curl http://localhost:8080/symbol/my-symbol-id

Response:

{
  "id": "my-symbol-id",
  "name": "ExampleSymbol",
  "kind": "function",
  "location": {
    "file": "example.go",
    "line": 42
  },
  "module": "example"
}

`GET /search`

Search for symbols matching a query.

Query Parameters:

q (required) - Search query
scope - Module ID to search within
kinds - Comma-separated list of symbol kinds
limit - Maximum results (default: 50)
merge - Merge strategy: "prefer-first" or "union"
repoStateMode - Repository state: "head" or "full"
depth - Search depth (default: 1)
includeExternal - Include external symbols (true/false)
refresh - Force refresh cache (true/false)

curl "http://localhost:8080/search?q=myFunction&limit=10&kinds=function,method"

Response:

{
  "query": "myFunction",
  "results": [],
  "total": 0,
  "hasMore": false,
  "timestamp": "2024-12-16T12:00:00Z"
}

`GET /refs/:id`

Find all references to a symbol.

curl http://localhost:8080/refs/my-symbol-id

Response:

{
  "symbolId": "my-symbol-id",
  "references": [],
  "total": 0,
  "timestamp": "2024-12-16T12:00:00Z"
}

Analysis

`GET /architecture`

Get an overview of the codebase architecture.

Query Parameters:

Parameter	Type	Default	Description
`granularity`	string	`module`	Level of detail: `module`, `directory`, `file`
`depth`	int	`2`	Maximum dependency depth
`includeExternalDeps`	bool	`false`	Include external dependencies
`inferModules`	bool	`true`	Infer modules from directory structure
`targetPath`	string		Focus on specific path (relative to repo root)
`refresh`	bool	`false`	Force refresh, bypass cache

# Module-level (default)
curl http://localhost:8080/architecture

# Directory-level (for single-module projects)
curl "http://localhost:8080/architecture?granularity=directory"

# File-level for specific path
curl "http://localhost:8080/architecture?granularity=file&targetPath=src/components"

Response (module granularity):

{
  "timestamp": "2024-12-16T12:00:00Z",
  "granularity": "module",
  "detectionMethod": "manifest",
  "modules": [],
  "dependencies": [],
  "entrypoints": []
}

Response (directory granularity):

{
  "timestamp": "2024-12-16T12:00:00Z",
  "granularity": "directory",
  "detectionMethod": "inferred",
  "directories": [],
  "directoryDependencies": []
}

`GET /impact/:id`

Analyze the impact of changing a symbol.

curl http://localhost:8080/impact/my-symbol-id

Response:

{
  "symbolId": "my-symbol-id",
  "timestamp": "2024-12-16T12:00:00Z",
  "impact": {},
  "affected": [],
  "risk": "low"
}

Ownership & Architecture

`GET /ownership`

Get ownership for a file path or module.

Query Parameters:

path - File path to query ownership for
moduleId - Module ID to query ownership for (alternative to path)
includeHistory - Include ownership change history (true/false)

# Get ownership for a file
curl "http://localhost:8080/ownership?path=internal/api/handler.go"

# Get ownership for a module
curl "http://localhost:8080/ownership?moduleId=internal/api"

# Include ownership history
curl "http://localhost:8080/ownership?path=internal/api/handler.go&includeHistory=true"

Response:

{
  "path": "internal/api/handler.go",
  "owners": [
    {
      "identity": "@api-team",
      "scope": "maintainer",
      "source": "codeowners",
      "confidence": 1.0
    },
    {
      "identity": "alice@example.com",
      "scope": "reviewer",
      "source": "git-blame",
      "confidence": 0.79,
      "weightedLines": 0.35
    }
  ],
  "suggestedReviewers": ["@api-team", "alice@example.com"],
  "timestamp": "2024-12-16T12:00:00Z"
}

`GET /responsibilities/:moduleId`

Get responsibilities for a module.

curl http://localhost:8080/responsibilities/internal/api

Response:

{
  "moduleId": "internal/api",
  "summary": "HTTP API handlers and middleware",
  "capabilities": ["request routing", "authentication", "response formatting"],
  "keySymbols": ["Handler", "Router", "Middleware"],
  "confidence": 0.85,
  "source": "inferred",
  "timestamp": "2024-12-16T12:00:00Z"
}

`GET /hotspots`

Get hotspot analysis with trend data.

Query Parameters:

scope - Module or path to scope analysis
days - Time window in days (default: 30)
limit - Maximum results (default: 20)

curl "http://localhost:8080/hotspots?scope=internal/query&days=30&limit=20"

Response:

{
  "hotspots": [
    {
      "targetId": "internal/query/engine.go",
      "score": 0.85,
      "trend": {
        "direction": "increasing",
        "velocity": 0.02,
        "projection30d": 0.91
      },
      "metrics": {
        "churnCommits30d": 12,
        "churnAuthors30d": 3,
        "complexityCyclomatic": 25
      }
    }
  ],
  "timestamp": "2024-12-16T12:00:00Z"
}

`GET /decisions`

List or search Architectural Decision Records.

Query Parameters:

moduleId - Filter by affected module
status - Filter by status (proposed, accepted, deprecated, superseded)
search - Full-text search in title and content

# List all decisions
curl http://localhost:8080/decisions

# Filter by module
curl "http://localhost:8080/decisions?moduleId=internal/api"

# Search decisions
curl "http://localhost:8080/decisions?search=caching"

Response:

{
  "decisions": [
    {
      "id": "ADR-001",
      "title": "Use SCIP for code indexing",
      "status": "accepted",
      "createdAt": "2024-12-01T10:00:00Z",
      "affectedModules": ["internal/backends/scip"]
    }
  ],
  "total": 1,
  "timestamp": "2024-12-16T12:00:00Z"
}

`POST /decisions`

Create a new Architectural Decision Record.

curl -X POST http://localhost:8080/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Use Redis for caching",
    "context": "We need distributed caching for multi-instance deployments...",
    "decision": "We will use Redis as our caching layer...",
    "consequences": ["Requires Redis infrastructure", "Enables horizontal scaling"],
    "affectedModules": ["internal/cache"],
    "status": "proposed"
  }'

Response:

{
  "id": "ADR-002",
  "path": "~/.ckb/repos/<hash>/decisions/ADR-002-use-redis-for-caching.md",
  "status": "created",
  "timestamp": "2024-12-16T12:00:00Z"
}

`POST /refresh`

Refresh the architectural model.

Request Body:

{
  "scope": "all",
  "force": false,
  "dryRun": false,
  "async": false
}

Scope options: all, modules, ownership, hotspots, responsibilities

# Refresh everything (synchronous)
curl -X POST http://localhost:8080/refresh \
  -H "Content-Type: application/json" \
  -d '{"scope": "all"}'

# Refresh asynchronously (v6.1)
curl -X POST http://localhost:8080/refresh \
  -H "Content-Type: application/json" \
  -d '{"scope": "all", "async": true}'

# Dry run
curl -X POST http://localhost:8080/refresh \
  -H "Content-Type: application/json" \
  -d '{"scope": "all", "dryRun": true}'

Response (sync):

{
  "status": "completed",
  "changes": {
    "modules": 5,
    "ownership": 12,
    "hotspots": 8,
    "responsibilities": 5
  },
  "duration": "2.5s",
  "timestamp": "2024-12-16T12:00:00Z"
}

Response (async):

{
  "jobId": "job-abc123",
  "status": "queued",
  "timestamp": "2024-12-16T12:00:00Z"
}

Background Jobs (v6.1)

`GET /jobs`

List background jobs with optional filters.

Query Parameters:

status - Filter by status: queued, running, completed, failed, cancelled
type - Filter by job type (e.g., "refresh-architecture")
limit - Maximum results (default: 20)

# List all jobs
curl http://localhost:8080/jobs

# List running jobs
curl "http://localhost:8080/jobs?status=running"

# List refresh jobs
curl "http://localhost:8080/jobs?type=refresh-architecture&limit=10"

Response:

{
  "jobs": [
    {
      "id": "job-abc123",
      "type": "refresh-architecture",
      "status": "running",
      "progress": 45,
      "createdAt": "2024-12-16T12:00:00Z",
      "startedAt": "2024-12-16T12:00:01Z"
    }
  ],
  "total": 1,
  "timestamp": "2024-12-16T12:00:05Z"
}

`GET /jobs/:id`

Get status and result of a specific job.

curl http://localhost:8080/jobs/job-abc123

Response (running):

{
  "id": "job-abc123",
  "type": "refresh-architecture",
  "status": "running",
  "progress": 75,
  "createdAt": "2024-12-16T12:00:00Z",
  "startedAt": "2024-12-16T12:00:01Z"
}

Response (completed):

{
  "id": "job-abc123",
  "type": "refresh-architecture",
  "status": "completed",
  "progress": 100,
  "createdAt": "2024-12-16T12:00:00Z",
  "startedAt": "2024-12-16T12:00:01Z",
  "completedAt": "2024-12-16T12:00:30Z",
  "result": {
    "changes": {
      "modules": 5,
      "ownership": 12,
      "hotspots": 8
    }
  }
}

`POST /jobs/:id/cancel`

Cancel a queued or running job.

curl -X POST http://localhost:8080/jobs/job-abc123/cancel

Response:

{
  "id": "job-abc123",
  "cancelled": true,
  "status": "cancelled",
  "timestamp": "2024-12-16T12:00:10Z"
}

CI/CD Integration (v6.1)

`POST /pr/summary`

Analyze a pull request for risk assessment and reviewer suggestions.

Request Body:

{
  "baseBranch": "main",
  "headBranch": "feature/my-feature",
  "includeOwnership": true
}

curl -X POST http://localhost:8080/pr/summary \
  -H "Content-Type: application/json" \
  -d '{"baseBranch": "main", "includeOwnership": true}'

Response:

{
  "filesChanged": 12,
  "linesAdded": 450,
  "linesRemoved": 120,
  "modulesAffected": ["internal/api", "internal/query"],
  "hotspotsTouched": [
    {
      "path": "internal/query/engine.go",
      "score": 0.85,
      "trend": "increasing"
    }
  ],
  "suggestedReviewers": ["@api-team", "alice@example.com"],
  "riskAssessment": "medium",
  "riskFactors": [
    "Touches 2 hotspot files",
    "Affects 2 modules"
  ],
  "timestamp": "2024-12-16T12:00:00Z"
}

`GET /ownership/drift`

Compare CODEOWNERS declarations vs actual git-blame ownership.

Query Parameters:

scope - Module or path to analyze (optional)
threshold - Minimum drift score 0.0-1.0 (default: 0.3)
limit - Maximum results (default: 20)

# Check all files for ownership drift
curl http://localhost:8080/ownership/drift

# Check specific module
curl "http://localhost:8080/ownership/drift?scope=internal/api&threshold=0.4"

Response:

{
  "driftedFiles": [
    {
      "path": "internal/api/handler.go",
      "declaredOwner": "@old-team",
      "actualOwners": [
        {"identity": "alice@example.com", "contribution": 0.65},
        {"identity": "bob@example.com", "contribution": 0.25}
      ],
      "driftScore": 0.85,
      "recommendation": "Update CODEOWNERS to reflect actual contributors"
    }
  ],
  "total": 1,
  "scope": "internal/api",
  "timestamp": "2024-12-16T12:00:00Z"
}

Federation (v6.2)

Cross-repository queries and unified visibility. See Federation for full documentation.

`GET /federations`

List all available federations.

curl http://localhost:8080/federations

Response:

{
  "federations": ["platform", "infrastructure"],
  "count": 2
}

`GET /federations/:name/status`

Get detailed status of a federation.

curl http://localhost:8080/federations/platform/status

Response:

{
  "name": "platform",
  "description": "Our microservices platform",
  "createdAt": "2024-12-18T10:00:00Z",
  "repoCount": 4,
  "repos": [
    {
      "repoId": "api",
      "repoUid": "550e8400-e29b-41d4-a716-446655440001",
      "path": "/code/api-service",
      "tags": ["backend"]
    }
  ],
  "compatibility": {
    "compatible": 3,
    "incompatible": 1
  }
}

`GET /federations/:name/repos`

List repositories in a federation.

Query Parameters:

includeCompatibility - Include schema compatibility status (default: false)

curl "http://localhost:8080/federations/platform/repos?includeCompatibility=true"

`GET /federations/:name/modules`

Search for modules across all repositories in the federation.

Query Parameters:

q - Search query (FTS)
repos - Comma-separated repo IDs to filter
tags - Comma-separated tags to filter
limit - Maximum results (default: 50)

# Find all authentication modules
curl "http://localhost:8080/federations/platform/modules?q=auth"

# Search in specific repos
curl "http://localhost:8080/federations/platform/modules?q=handler&repos=api,web"

Response:

{
  "modules": [
    {
      "repoId": "api",
      "moduleId": "internal/auth",
      "name": "auth",
      "responsibility": "User authentication and session management",
      "ownerRef": "@security-team"
    }
  ],
  "total": 1,
  "staleness": {
    "overallStaleness": "fresh",
    "refreshRecommended": false
  }
}

`GET /federations/:name/ownership`

Search for ownership patterns across repositories.

Query Parameters:

path - Path glob pattern (e.g., **/api/**)
repos - Comma-separated repo IDs to filter
limit - Maximum results (default: 50)

curl "http://localhost:8080/federations/platform/ownership?path=**/api/**"

`GET /federations/:name/hotspots`

Get merged hotspots across all repositories.

Query Parameters:

repos - Comma-separated repo IDs to filter
top - Number of top hotspots (default: 20)
minScore - Minimum score threshold (default: 0.3)

curl "http://localhost:8080/federations/platform/hotspots?top=10"

Response:

{
  "hotspots": [
    {
      "repoId": "api",
      "targetId": "internal/query/engine.go",
      "targetType": "file",
      "score": 0.85,
      "churnCommits30d": 15,
      "complexityCyclomatic": 25.5
    }
  ],
  "total": 10,
  "staleness": {
    "overallStaleness": "fresh",
    "refreshRecommended": false
  }
}

`GET /federations/:name/decisions`

Search for architectural decisions across repositories.

Query Parameters:

q - Search query (FTS)
status - Comma-separated status filter (proposed, accepted, deprecated, superseded)
repos - Comma-separated repo IDs to filter
module - Filter by affected module
limit - Maximum results (default: 50)

# Find all accepted authentication decisions
curl "http://localhost:8080/federations/platform/decisions?q=authentication&status=accepted"

`POST /federations/:name/sync`

Sync federation index from repository data.

Request Body:

{
  "force": false,
  "dryRun": false,
  "repoIds": ["api", "auth"]
}

curl -X POST http://localhost:8080/federations/platform/sync \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

Response:

{
  "results": [
    {
      "repoId": "api",
      "status": "success",
      "modulesSynced": 5,
      "ownershipSynced": 12,
      "hotspotsSynced": 20,
      "decisionsSynced": 3,
      "duration": "250ms"
    }
  ],
  "summary": {
    "success": 4,
    "failed": 0,
    "skipped": 0,
    "total": 4
  }
}

Complexity Analysis (v6.2.2)

Tree-sitter based code complexity metrics.

`GET /complexity`

Get complexity metrics for a source file.

Query Parameters:

path - File path (required)
includeFunctions - Include per-function breakdown (default: true)
limit - Maximum functions to return (default: 20)
sortBy - Sort by: "cyclomatic", "cognitive", or "lines" (default: "cyclomatic")

# Get complexity for a file
curl "http://localhost:8080/complexity?path=internal/query/engine.go"

# Get top 10 most complex functions
curl "http://localhost:8080/complexity?path=internal/query/engine.go&limit=10&sortBy=cognitive"

Response:

{
  "filePath": "internal/query/engine.go",
  "language": "go",
  "aggregate": {
    "totalCyclomatic": 145,
    "totalCognitive": 89,
    "averageCyclomatic": 8.5,
    "averageCognitive": 5.2,
    "maxCyclomatic": 25,
    "maxCognitive": 18,
    "functionCount": 17,
    "lineCount": 450
  },
  "functions": [
    {
      "name": "ExecuteQuery",
      "line": 42,
      "endLine": 98,
      "cyclomatic": 25,
      "cognitive": 18,
      "lines": 56,
      "parameters": 3
    },
    {
      "name": "mergeResults",
      "line": 120,
      "endLine": 145,
      "cyclomatic": 12,
      "cognitive": 8,
      "lines": 25,
      "parameters": 2
    }
  ],
  "timestamp": "2024-12-18T12:00:00Z"
}

Supported Languages:

Go, JavaScript, TypeScript, Python, Rust, Java, Kotlin

Complexity Types:

Cyclomatic — Decision points (if, for, while, switch, &&, ||)
Cognitive — Nesting-weighted complexity for maintainability

Contract Analysis (v6.3)

Cross-repo API contract analysis for protobuf and OpenAPI specifications.

`GET /federations/:name/contracts`

List API contracts in a federation.

Query Parameters:

repoId - Filter to contracts from this repo
contractType - Filter by type: "proto" or "openapi"
visibility - Filter by visibility: "public", "internal", or "unknown"
limit - Maximum results (default: 50)

# List all contracts
curl http://localhost:8080/federations/platform/contracts

# Filter by repo and type
curl "http://localhost:8080/federations/platform/contracts?repoId=api&contractType=proto&visibility=public"

Response:

{
  "contracts": [
    {
      "repoId": "api",
      "path": "proto/api/v1/user.proto",
      "contractType": "proto",
      "visibility": "public",
      "lastModified": "2024-12-15T10:00:00Z"
    }
  ],
  "total": 1,
  "timestamp": "2024-12-18T12:00:00Z"
}

`POST /federations/:name/contracts/impact`

Analyze impact of changing an API contract.

Request Body:

{
  "repoId": "api",
  "path": "proto/api/v1/user.proto",
  "includeTransitive": true,
  "includeHeuristic": false,
  "maxDepth": 3
}

curl -X POST http://localhost:8080/federations/platform/contracts/impact \
  -H "Content-Type: application/json" \
  -d '{
    "repoId": "api",
    "path": "proto/api/v1/user.proto",
    "includeTransitive": true
  }'

Response:

{
  "contract": {
    "repoId": "api",
    "path": "proto/api/v1/user.proto",
    "visibility": "public"
  },
  "directConsumers": [
    {
      "repoId": "web",
      "edgeId": 123,
      "tier": "declared",
      "confidence": 1.0,
      "evidence": "proto import in web/proto/deps.proto"
    }
  ],
  "transitiveConsumers": [
    {
      "repoId": "mobile",
      "depth": 2,
      "path": ["api", "web", "mobile"],
      "confidence": 0.85
    }
  ],
  "riskAssessment": {
    "level": "high",
    "factors": [
      "Public contract with 3 direct consumers",
      "Transitive impact reaches 5 repos"
    ]
  },
  "ownership": {
    "contractOwners": ["@api-team"],
    "affectedOwners": ["@web-team", "@mobile-team"]
  },
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /federations/:name/contracts/deps`

Get contract dependencies for a repository.

Query Parameters:

repoId - Repository to analyze (required)
direction - "consumers", "dependencies", or "both" (default: "both")
moduleId - Optional module filter
includeHeuristic - Include tier 3 heuristic edges (default: false)

# Get all contract dependencies
curl "http://localhost:8080/federations/platform/contracts/deps?repoId=api&direction=both"

# Get only consumers
curl "http://localhost:8080/federations/platform/contracts/deps?repoId=api&direction=consumers"

Response:

{
  "repoId": "api",
  "consumers": [
    {
      "repoId": "web",
      "contracts": ["proto/api/v1/user.proto", "proto/api/v1/order.proto"],
      "tier": "declared",
      "confidence": 1.0
    }
  ],
  "dependencies": [
    {
      "repoId": "common",
      "contracts": ["proto/common/types.proto"],
      "tier": "declared",
      "confidence": 1.0
    }
  ],
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /federations/:name/contracts/stats`

Get contract statistics for a federation.

curl http://localhost:8080/federations/platform/contracts/stats

Response:

{
  "totalContracts": 45,
  "byType": {
    "proto": 32,
    "openapi": 13
  },
  "byVisibility": {
    "public": 28,
    "internal": 12,
    "unknown": 5
  },
  "totalEdges": 156,
  "edgesByTier": {
    "declared": 89,
    "derived": 52,
    "heuristic": 15
  },
  "timestamp": "2024-12-18T12:00:00Z"
}

`POST /federations/:name/contracts/edges/:edgeId/suppress`

Suppress a false positive contract dependency edge.

curl -X POST http://localhost:8080/federations/platform/contracts/edges/123/suppress \
  -H "Content-Type: application/json" \
  -d '{"reason": "Not actually used - legacy import"}'

Response:

{
  "edgeId": 123,
  "suppressed": true,
  "reason": "Not actually used - legacy import",
  "timestamp": "2024-12-18T12:00:00Z"
}

`POST /federations/:name/contracts/edges/:edgeId/verify`

Verify a contract dependency edge (increase confidence).

curl -X POST http://localhost:8080/federations/platform/contracts/edges/123/verify

Response:

{
  "edgeId": 123,
  "verified": true,
  "previousConfidence": 0.7,
  "newConfidence": 1.0,
  "timestamp": "2024-12-18T12:00:00Z"
}

Telemetry (v6.4)

Runtime telemetry integration for observed usage and dead code detection.

`GET /telemetry/status`

Get telemetry status and coverage metrics.

curl http://localhost:8080/telemetry/status

Response:

{
  "enabled": true,
  "lastSync": "2024-12-18T10:30:00Z",
  "coverage": {
    "attribute": 0.85,
    "match": 0.72,
    "service": 0.80,
    "overall": 0.76,
    "level": "medium"
  },
  "unmappedServices": ["legacy-batch-processor"],
  "warnings": ["Sampling pattern detected - low-traffic functions may be missed"],
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /telemetry/usage/:symbolId`

Get observed usage for a symbol.

Query Parameters:

period - Time period: "7d", "30d", "90d", or "all" (default: "90d")
includeCallers - Include caller breakdown (default: false)

curl "http://localhost:8080/telemetry/usage/ckb:repo:sym:abc123?period=30d&includeCallers=true"

Response:

{
  "symbolId": "ckb:repo:sym:abc123",
  "callCount": 15420,
  "errorCount": 23,
  "matchQuality": "exact",
  "matchConfidence": 0.95,
  "trend": "stable",
  "callers": [
    {
      "service": "api-gateway",
      "callCount": 12000,
      "lastSeen": "2024-12-18T11:59:00Z"
    },
    {
      "service": "web-frontend",
      "callCount": 3420,
      "lastSeen": "2024-12-18T11:58:00Z"
    }
  ],
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /telemetry/dead-code`

Find dead code candidates.

Query Parameters:

repoId - Repository ID (optional, defaults to current repo)
minConfidence - Minimum confidence 0-1 (default: 0.7)
limit - Maximum results (default: 100)

curl "http://localhost:8080/telemetry/dead-code?minConfidence=0.8&limit=50"

Response:

{
  "candidates": [
    {
      "symbolId": "ckb:repo:sym:xyz789",
      "name": "LegacyExporter.Export",
      "filePath": "internal/export/v1.go",
      "line": 42,
      "staticRefs": 3,
      "observedCalls": 0,
      "matchQuality": "exact",
      "confidence": 0.82,
      "reasons": ["90+ days observation", "exact match"]
    }
  ],
  "summary": {
    "totalAnalyzed": 1247,
    "candidateCount": 3,
    "coverageLevel": "medium",
    "observationDays": 120
  },
  "coverage": {
    "overall": 0.76,
    "level": "medium"
  },
  "limitations": [
    "Sampling may cause false positives for low-traffic functions"
  ],
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /telemetry/unmapped`

List services that couldn't be mapped to repositories.

curl http://localhost:8080/telemetry/unmapped

Response:

{
  "services": [
    {
      "name": "legacy-batch-processor",
      "eventCount": 1500,
      "lastSeen": "2024-12-18T10:00:00Z"
    },
    {
      "name": "internal-cron-runner",
      "eventCount": 200,
      "lastSeen": "2024-12-17T23:00:00Z"
    }
  ],
  "total": 2,
  "timestamp": "2024-12-18T12:00:00Z"
}

`POST /v1/metrics`

OTLP ingest endpoint for OpenTelemetry Collector.

Accepts standard OTLP metrics format. See Configuration for required attributes.

# Configure OTEL Collector to export to this endpoint
# See Configuration guide for full setup

`POST /api/v1/ingest/json`

Simplified JSON ingest for development/testing.

curl -X POST http://localhost:8080/api/v1/ingest/json \
  -H "Content-Type: application/json" \
  -d '{
    "calls": [
      {
        "service_name": "api-gateway",
        "function_name": "HandleRequest",
        "file_path": "internal/api/handler.go",
        "namespace": "api",
        "call_count": 1500,
        "error_count": 3
      }
    ]
  }'

Response:

{
  "status": "success",
  "eventsReceived": 1,
  "eventsMatched": 1,
  "eventsUnmatched": 0,
  "timestamp": "2024-12-18T12:00:00Z"
}

Doc-Symbol Linking (v7.3)

Bridge documentation and code with automatic symbol detection.

`POST /docs/index`

Scan and index documentation for symbol references.

Request Body:

{
  "force": false
}

# Index docs (incremental)
curl -X POST http://localhost:8080/docs/index

# Force re-index all docs
curl -X POST http://localhost:8080/docs/index \
  -H "Content-Type: application/json" \
  -d '{"force": true}'

Response:

{
  "filesIndexed": 12,
  "symbolsFound": 156,
  "resolved": 142,
  "unresolved": 14,
  "duration": "1.2s",
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /docs/symbol/:name`

Find documentation that references a symbol.

Query Parameters:

limit - Maximum results (default: 10)

curl "http://localhost:8080/docs/symbol/Engine.Start?limit=5"

Response:

{
  "symbol": "Engine.Start",
  "docs": [
    {
      "path": "docs/architecture.md",
      "line": 42,
      "context": "The `Engine.Start` method initializes...",
      "resolution": "resolved",
      "symbolId": "ckb:repo:sym:abc123"
    }
  ],
  "total": 1,
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /docs/file/:path`

List all symbol references in a documentation file.

curl "http://localhost:8080/docs/file/docs/architecture.md"

Response:

{
  "path": "docs/architecture.md",
  "symbols": [
    {
      "rawText": "Engine.Start",
      "line": 42,
      "resolution": "resolved",
      "symbolId": "ckb:repo:sym:abc123",
      "kind": "method"
    },
    {
      "rawText": "OldFunction",
      "line": 58,
      "resolution": "stale",
      "reason": "symbol_deleted"
    }
  ],
  "summary": {
    "total": 15,
    "resolved": 14,
    "stale": 1
  },
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /docs/stale`

Check documentation for stale symbol references.

Query Parameters:

path - Specific file to check (optional, checks all if omitted)

# Check all docs
curl http://localhost:8080/docs/stale

# Check specific file
curl "http://localhost:8080/docs/stale?path=docs/api.md"

Response:

{
  "reports": [
    {
      "docPath": "docs/api.md",
      "stale": [
        {
          "rawText": "OldHandler",
          "line": 23,
          "reason": "symbol_renamed",
          "suggestion": "NewHandler"
        }
      ]
    }
  ],
  "totalStale": 1,
  "totalDocs": 12,
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /docs/coverage`

Get documentation coverage statistics.

Query Parameters:

exportedOnly - Only count exported/public symbols (default: false)
topN - Number of undocumented symbols to return (default: 10)

curl "http://localhost:8080/docs/coverage?exportedOnly=true&topN=5"

Response:

{
  "totalSymbols": 450,
  "documentedSymbols": 312,
  "coverage": 0.69,
  "topUndocumented": [
    {
      "symbolId": "ckb:repo:sym:xyz789",
      "name": "CriticalFunction",
      "kind": "function",
      "centrality": 0.85,
      "filePath": "internal/core/engine.go",
      "line": 120
    }
  ],
  "timestamp": "2024-12-18T12:00:00Z"
}

`GET /docs/module/:moduleId`

Find documentation linked to a module via directives.

curl "http://localhost:8080/docs/module/internal/query"

Response:

{
  "moduleId": "internal/query",
  "docs": [
    {
      "path": "docs/query-engine.md",
      "directive": "<!-- ckb:module internal/query -->",
      "line": 1
    }
  ],
  "total": 1,
  "timestamp": "2024-12-18T12:00:00Z"
}

Remote Index Serving (v7.3)

Serve symbol indexes over HTTP for remote federation clients. Enable with --index-server flag.

# Start with index server enabled
ckb serve --index-server --index-config config.toml

Authentication (v7.3)

When authentication is enabled, requests require a Bearer token:

curl -H "Authorization: Bearer ckb_sk_..." http://localhost:8080/index/repos

Scopes control access: read for GET requests, write for uploads, admin for deletions and token management.

See Authentication for complete documentation on token management, configuration, scopes, and error handling.

`GET /index/repos`

List all indexed repositories.

curl http://localhost:8080/index/repos

Response:

{
  "data": {
    "repos": [
      {
        "id": "company/core-lib",
        "name": "Core Library",
        "description": "Shared utilities",
        "languages": ["go"],
        "commit": "abc123",
        "index_version": "1.0",
        "sync_seq": 42,
        "indexed_at": 1703001600,
        "symbol_count": 1500,
        "file_count": 120
      }
    ]
  },
  "meta": {
    "timestamp": 1703001700
  }
}

`GET /index/repos/{repo}/meta`

Get repository metadata and capabilities.

curl http://localhost:8080/index/repos/company%2Fcore-lib/meta

Response:

{
  "data": {
    "id": "company/core-lib",
    "name": "Core Library",
    "commit": "abc123",
    "index_version": "1.0",
    "sync_seq": 42,
    "sync_log_retention_seq_min": 0,
    "schema_version": 8,
    "indexed_at": 1703001600,
    "languages": ["go"],
    "stats": {
      "files": 120,
      "symbols": 1500,
      "refs": 8500,
      "call_edges": 3200
    },
    "capabilities": {
      "sync_seq": true,
      "search": true,
      "batch_get": true,
      "compression": [],
      "redaction": true,
      "max_page_size": 10000
    },
    "privacy": {
      "paths_exposed": true,
      "docs_exposed": true,
      "signatures_exposed": true
    }
  },
  "meta": {
    "timestamp": 1703001700
  }
}

`GET /index/repos/{repo}/files`

List files with cursor-based pagination.

Query Parameters:

cursor - Pagination cursor
limit - Maximum results (default: 1000)

curl "http://localhost:8080/index/repos/company%2Fcore-lib/files?limit=100"

Response:

{
  "data": {
    "files": [
      {
        "path": "internal/api/handler.go",
        "basename": "handler.go",
        "language": "go",
        "symbol_count": 25,
        "hash": "abc123"
      }
    ]
  },
  "meta": {
    "sync_seq": 42,
    "cursor": "eyJlIjoiZmlsZSIsInBrIjoiMTIzIn0.signature",
    "has_more": true,
    "timestamp": 1703001700
  }
}

`GET /index/repos/{repo}/symbols`

List symbols with filtering and cursor-based pagination.

Query Parameters:

cursor - Pagination cursor
limit - Maximum results (default: 1000)
language - Filter by language
kind - Filter by symbol kind (function, method, class, etc.)
file - Filter by file path

curl "http://localhost:8080/index/repos/company%2Fcore-lib/symbols?kind=function&limit=50"

Response:

{
  "data": {
    "symbols": [
      {
        "id": "ckb:company/core-lib:sym:abc123",
        "name": "HandleRequest",
        "kind": "function",
        "file_path": "internal/api/handler.go",
        "file_basename": "handler.go",
        "line": 42,
        "column": 6,
        "language": "go",
        "documentation": "HandleRequest processes incoming HTTP requests",
        "signature": "func HandleRequest(w http.ResponseWriter, r *http.Request)",
        "container": "api"
      }
    ]
  },
  "meta": {
    "sync_seq": 42,
    "cursor": "eyJlIjoic3ltYm9sIiwicGsiOiI0NTYifQ.signature",
    "has_more": true,
    "total": 1500,
    "timestamp": 1703001700
  }
}

`GET /index/repos/{repo}/symbols/{id}`

Get a single symbol by ID.

curl http://localhost:8080/index/repos/company%2Fcore-lib/symbols/ckb:company%2Fcore-lib:sym:abc123

Response:

{
  "data": {
    "symbol": {
      "id": "ckb:company/core-lib:sym:abc123",
      "name": "HandleRequest",
      "kind": "function",
      "file_path": "internal/api/handler.go",
      "line": 42,
      "language": "go"
    }
  },
  "meta": {
    "sync_seq": 42,
    "timestamp": 1703001700
  }
}

`POST /index/repos/{repo}/symbols:batchGet`

Batch get multiple symbols by ID.

Request Body:

{
  "ids": ["ckb:repo:sym:abc", "ckb:repo:sym:def", "ckb:repo:sym:xyz"]
}

curl -X POST http://localhost:8080/index/repos/company%2Fcore-lib/symbols:batchGet \
  -H "Content-Type: application/json" \
  -d '{"ids": ["ckb:repo:sym:abc", "ckb:repo:sym:def"]}'

Response:

{
  "data": {
    "symbols": [
      {"id": "ckb:repo:sym:abc", "name": "FunctionA", "kind": "function"},
      {"id": "ckb:repo:sym:def", "name": "FunctionB", "kind": "function"}
    ],
    "not_found": ["ckb:repo:sym:xyz"]
  },
  "meta": {
    "sync_seq": 42,
    "timestamp": 1703001700
  }
}

`GET /index/repos/{repo}/refs`

List references (call edges) with filtering and pagination.

Query Parameters:

cursor - Pagination cursor
limit - Maximum results (default: 1000)
from_file - Filter by source file
to_symbol_id - Filter by target symbol ID
language - Filter by language

curl "http://localhost:8080/index/repos/company%2Fcore-lib/refs?to_symbol_id=ckb:repo:sym:abc"

Response:

{
  "data": {
    "refs": [
      {
        "from_file": "internal/api/router.go",
        "to_symbol_id": "ckb:repo:sym:abc",
        "line": 58,
        "col": 12,
        "kind": "call",
        "language": "go"
      }
    ]
  },
  "meta": {
    "sync_seq": 42,
    "has_more": false,
    "timestamp": 1703001700
  }
}

`GET /index/repos/{repo}/callgraph`

List call graph edges with filtering and pagination.

Query Parameters:

cursor - Pagination cursor
limit - Maximum results (default: 1000)
caller_id - Filter by caller symbol ID
callee_id - Filter by callee symbol ID
caller_file - Filter by caller file
language - Filter by language

curl "http://localhost:8080/index/repos/company%2Fcore-lib/callgraph?callee_id=ckb:repo:sym:abc"

Response:

{
  "data": {
    "edges": [
      {
        "caller_id": "ckb:repo:sym:xyz",
        "callee_id": "ckb:repo:sym:abc",
        "caller_file": "internal/api/router.go",
        "call_line": 58,
        "call_col": 12,
        "language": "go"
      }
    ]
  },
  "meta": {
    "sync_seq": 42,
    "has_more": false,
    "timestamp": 1703001700
  }
}

`GET /index/repos/{repo}/search/symbols`

Search symbols by name.

Query Parameters:

q - Search query (required)
limit - Maximum results (default: 100)
language - Filter by language
kind - Filter by symbol kind

curl "http://localhost:8080/index/repos/company%2Fcore-lib/search/symbols?q=Handle&kind=function"

Response:

{
  "data": {
    "symbols": [
      {
        "id": "ckb:repo:sym:abc",
        "name": "HandleRequest",
        "kind": "function",
        "file_path": "internal/api/handler.go",
        "line": 42
      }
    ],
    "truncated": false
  },
  "meta": {
    "sync_seq": 42,
    "timestamp": 1703001700
  }
}

`GET /index/repos/{repo}/search/files`

Search files by path.

Query Parameters:

q - Search query (required)
limit - Maximum results (default: 100)

curl "http://localhost:8080/index/repos/company%2Fcore-lib/search/files?q=handler"

Response:

{
  "data": {
    "files": [
      {
        "path": "internal/api/handler.go",
        "basename": "handler.go",
        "language": "go",
        "symbol_count": 25
      }
    ],
    "truncated": false
  },
  "meta": {
    "sync_seq": 42,
    "timestamp": 1703001700
  }
}

Index Server Configuration

Configure via TOML file:

[index_server]
enabled = true
max_page_size = 10000
cursor_secret = "your-secret-key"  # Optional, auto-generated if not set

[[repos]]
id = "company/core-lib"
name = "Core Library"
path = "/repos/core-lib"
description = "Shared utilities"

[[repos]]
id = "company/api"
name = "API Service"
path = "/repos/api"

[repos.privacy]
expose_paths = true
expose_docs = false
expose_signatures = false
path_prefix_strip = "/home/build/"

[default_privacy]
expose_paths = true
expose_docs = true
expose_signatures = true

Privacy Redaction

Per-repo privacy controls:

expose_paths - Whether to include full file paths (false = basename only)
expose_docs - Whether to include documentation strings
expose_signatures - Whether to include function signatures
path_prefix_strip - Remove this prefix from all paths

Cursor Security

Pagination cursors are HMAC-signed to prevent tampering. The server rejects invalid or tampered cursors with a 400 error.

Cache Operations

`POST /cache/warm`

Initiate cache warming for commonly accessed data.

curl -X POST http://localhost:8080/cache/warm

Response:

{
  "status": "success",
  "message": "Cache warming initiated",
  "timestamp": "2024-12-16T12:00:00Z"
}

`POST /cache/clear`

Clear all cached data.

curl -X POST http://localhost:8080/cache/clear

Response:

{
  "status": "success",
  "message": "Cache cleared",
  "timestamp": "2024-12-16T12:00:00Z"
}

Documentation

`GET /openapi.json`

Get the OpenAPI 3.0 specification for the API.

curl http://localhost:8080/openapi.json

Error Responses

All errors return a consistent JSON structure with remediation guidance (v8.0):

{
  "error": "Symbol not found",
  "code": "SYMBOL_NOT_FOUND",
  "details": null,
  "suggestedFixes": [
    {
      "type": "run-command",
      "command": "ckb doctor",
      "safe": true,
      "description": "Check system configuration"
    }
  ],
  "drilldowns": []
}

Error Codes (v8.0)

Code	Description	Remediation
`SYMBOL_NOT_FOUND`	Symbol ID doesn't exist in the index	Verify symbol ID or run `ckb search` to find correct ID
`FILE_NOT_FOUND`	File path doesn't exist	Check path spelling and ensure file is tracked
`INDEX_STALE`	SCIP index is out of date	Run `ckb index` or use `reindex` MCP tool
`BACKEND_UNAVAILABLE`	Required backend is not available	Run `ckb doctor` to diagnose, then fix as suggested
`AMBIGUOUS_QUERY`	Multiple symbols match the query	Narrow query with scope, kind, or more specific name
`PARTIAL_RESULT`	Some backends failed but partial data available	Result is incomplete; check backend health
`INVALID_PARAMETER`	Input parameter is invalid	Check parameter format and constraints
`RESOURCE_NOT_FOUND`	Requested resource doesn't exist	Verify resource ID or path
`PRECONDITION_FAILED`	Required precondition not met	Check index freshness, backend availability
`OPERATION_FAILED`	Operation could not be completed	Check logs for details, retry or escalate
`TIMEOUT`	Request timed out	Reduce query scope or increase timeout
`BUDGET_EXCEEDED`	Response would exceed token budget	Use more specific query or increase budget
`RATE_LIMITED`	Too many requests	Back off and retry with exponential delay

HTTP Status Codes

Status	Meaning
200	Success
400	Bad Request - Invalid parameters
404	Not Found - Resource doesn't exist
410	Gone - Resource was deleted
412	Precondition Failed - Index stale
413	Payload Too Large - Budget exceeded
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limited
500	Internal Server Error
503	Service Unavailable - Backend unavailable
504	Gateway Timeout

Request Headers

Supported Headers

X-Request-ID - Custom request ID (auto-generated if not provided)
Content-Type: application/json - For POST requests

Response Headers

Content-Type: application/json - All responses are JSON
X-Request-ID - Request ID for tracing
Access-Control-Allow-Origin: * - CORS enabled for local dev

Middleware

The API includes the following middleware (in order):

CORS - Enables cross-origin requests
Request ID - Generates unique request IDs
Logging - Logs all requests and responses
Recovery - Recovers from panics

Testing

Manual Testing

# Start server
./ckb serve --port 8081

# Test all endpoints
curl http://localhost:8081/health | jq .
curl http://localhost:8081/status | jq .
curl "http://localhost:8081/search?q=test" | jq .
curl -X POST http://localhost:8081/cache/clear | jq .

Using jq for Pretty Output

# Install jq if not already installed
brew install jq  # macOS
apt-get install jq  # Linux

# Pretty print responses
curl -s http://localhost:8080/status | jq .

Configuration

Server configuration via command-line flags:

Flag	Default	Description
`--port`	8080	Port to listen on
`--host`	localhost	Host to bind to

Graceful Shutdown

The server supports graceful shutdown via interrupt signals:

# Press Ctrl+C to stop the server
# Or send SIGTERM
kill -TERM <pid>

The server will:

Stop accepting new connections
Wait for active requests to complete (up to 10 seconds)
Shut down cleanly

Logging

The API logs all requests and responses with:

HTTP method and path
Query parameters
Status code
Response time
Request ID

Example log output:

2024-12-16T12:00:00Z [info] HTTP request | method=GET, path=/status, requestID=abc-123
2024-12-16T12:00:01Z [info] HTTP response | method=GET, path=/status, status=200, duration=100ms, requestID=abc-123

Development

Building

go build -o ckb ./cmd/ckb

Running in Development

# Start with default settings
./ckb serve

# Start with custom port for development
./ckb serve --port 8081

Testing with curl

# Save to file
curl http://localhost:8080/status > status.json

# Show headers
curl -i http://localhost:8080/health

# Show request/response with verbose
curl -v http://localhost:8080/ready

Integration

With Frontend Applications

// Fetch status
fetch('http://localhost:8080/status')
  .then(res => res.json())
  .then(data => console.log(data));

// Search symbols
fetch('http://localhost:8080/search?q=myFunction&limit=10')
  .then(res => res.json())
  .then(data => console.log(data));

With Other Tools

# HTTPie
http GET localhost:8080/status

# wget
wget -qO- http://localhost:8080/health

# Python
python -c "import requests; print(requests.get('http://localhost:8080/status').json())"

Troubleshooting

Server won't start

# Check if port is already in use
lsof -i :8080

# Use different port
./ckb serve --port 8081

Connection refused

# Verify server is running
ps aux | grep ckb

# Check server logs for errors
./ckb serve 2>&1 | tee server.log

Invalid JSON responses

# Validate JSON
curl http://localhost:8080/status | jq .

# Check response headers
curl -i http://localhost:8080/status

Support

For issues or questions:

Check the OpenAPI spec: GET /openapi.json
Review server logs
Check the implementation documentation: PHASE-4.2-IMPLEMENTATION.md

Related Pages

MCP-Integration — MCP tool setup for AI assistants
Presets — Tool presets and token optimization
Authentication — API token management
Configuration — Server configuration options
Prompt-Cookbook — Example queries and workflows

API Reference

CKB HTTP API

Quick Start

API Endpoints

System & Health

GET /

GET /health

GET /health/detailed (v7.3)

GET /ready

GET /status

Diagnostics

GET /doctor

POST /doctor/fix

Indexing (v7.1/v7.2)

POST /index

GET /index/status

Delta Ingestion (v7.3)

GET /delta

POST /delta/validate

POST /delta/ingest

Prometheus Metrics (v7.3)

GET /metrics

Language Quality (v7.3)

GET /meta/languages

GET /meta/python-env

GET /meta/typescript-monorepo

Symbol Operations

GET /symbol/:id

GET /search

GET /refs/:id

Analysis

GET /architecture

GET /impact/:id

Ownership & Architecture

GET /ownership

GET /responsibilities/:moduleId

GET /hotspots

GET /decisions

POST /decisions

POST /refresh

Background Jobs (v6.1)

GET /jobs

GET /jobs/:id

POST /jobs/:id/cancel

CI/CD Integration (v6.1)

POST /pr/summary

GET /ownership/drift

Federation (v6.2)

GET /federations

GET /federations/:name/status

GET /federations/:name/repos

GET /federations/:name/modules

GET /federations/:name/ownership

GET /federations/:name/hotspots

GET /federations/:name/decisions

POST /federations/:name/sync

Complexity Analysis (v6.2.2)

GET /complexity

Contract Analysis (v6.3)

GET /federations/:name/contracts

POST /federations/:name/contracts/impact

GET /federations/:name/contracts/deps

GET /federations/:name/contracts/stats

POST /federations/:name/contracts/edges/:edgeId/suppress

POST /federations/:name/contracts/edges/:edgeId/verify

Telemetry (v6.4)

GET /telemetry/status

GET /telemetry/usage/:symbolId

GET /telemetry/dead-code

GET /telemetry/unmapped

POST /v1/metrics

POST /api/v1/ingest/json

Doc-Symbol Linking (v7.3)

POST /docs/index

GET /docs/symbol/:name

GET /docs/file/:path

GET /docs/stale

GET /docs/coverage

GET /docs/module/:moduleId

Remote Index Serving (v7.3)

`GET /`

`GET /health`

`GET /health/detailed` (v7.3)

`GET /ready`

`GET /status`

`GET /doctor`

`POST /doctor/fix`

`POST /index`

`GET /index/status`

`GET /delta`

`POST /delta/validate`

`POST /delta/ingest`

`GET /metrics`

`GET /meta/languages`

`GET /meta/python-env`

`GET /meta/typescript-monorepo`

`GET /symbol/:id`

`GET /search`

`GET /refs/:id`

`GET /architecture`

`GET /impact/:id`

`GET /ownership`

`GET /responsibilities/:moduleId`

`GET /hotspots`

`GET /decisions`

`POST /decisions`

`POST /refresh`

`GET /jobs`

`GET /jobs/:id`

`POST /jobs/:id/cancel`

`POST /pr/summary`

`GET /ownership/drift`

`GET /federations`

`GET /federations/:name/status`

`GET /federations/:name/repos`

`GET /federations/:name/modules`

`GET /federations/:name/ownership`

`GET /federations/:name/hotspots`

`GET /federations/:name/decisions`

`POST /federations/:name/sync`

`GET /complexity`

`GET /federations/:name/contracts`

`POST /federations/:name/contracts/impact`

`GET /federations/:name/contracts/deps`

`GET /federations/:name/contracts/stats`

`POST /federations/:name/contracts/edges/:edgeId/suppress`

`POST /federations/:name/contracts/edges/:edgeId/verify`

`GET /telemetry/status`

`GET /telemetry/usage/:symbolId`

`GET /telemetry/dead-code`

`GET /telemetry/unmapped`

`POST /v1/metrics`

`POST /api/v1/ingest/json`

`POST /docs/index`

`GET /docs/symbol/:name`

`GET /docs/file/:path`

`GET /docs/stale`

`GET /docs/coverage`

`GET /docs/module/:moduleId`

`GET /index/repos`

`GET /index/repos/{repo}/meta`

`GET /index/repos/{repo}/files`

`GET /index/repos/{repo}/symbols`

`GET /index/repos/{repo}/symbols/{id}`

`POST /index/repos/{repo}/symbols:batchGet`

`GET /index/repos/{repo}/refs`

`GET /index/repos/{repo}/callgraph`

`GET /index/repos/{repo}/search/symbols`

`GET /index/repos/{repo}/search/files`

`POST /cache/warm`

`POST /cache/clear`

`GET /openapi.json`