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 /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"
}

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.

curl http://localhost:8080/architecture

Response:

{
  "timestamp": "2024-12-16T12:00:00Z",
  "modules": [],
  "dependencies": [],
  "metrics": {}
}

`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"
}

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:

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

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

Uh oh!

API Reference

CKB HTTP API

Quick Start

API Endpoints

System & Health

GET /

GET /health

GET /ready

GET /status

Diagnostics

GET /doctor

POST /doctor/fix

Indexing (v7.1/v7.2)

POST /index

GET /index/status

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

Cache Operations

POST /cache/warm

POST /cache/clear

Documentation

GET /openapi.json

Error Responses

HTTP Status Codes

Request Headers

Supported Headers

Response Headers

Middleware

`GET /`

`GET /health`

`GET /ready`

`GET /status`

`GET /doctor`

`POST /doctor/fix`

`POST /index`

`GET /index/status`

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

`POST /cache/warm`

`POST /cache/clear`

`GET /openapi.json`