Analysis API

Endpoints for code analysis and AI-powered insights.

Semantic Search

Search code using natural language.

POST /v1/projects/:id/search

Request Body:

{
  "query": "user authentication flow",
  "limit": 10
}

Response:

{
  "success": true,
  "results": [
    {
      "filePath": "src/auth/login.ts",
      "lineStart": 45,
      "lineEnd": 78,
      "content": "async function authenticate(email, password) {...}",
      "score": 0.92,
      "context": "LoginService - handles user authentication"
    }
  ]
}

Ask AI Assistant

Ask questions about your codebase.

POST /v1/projects/:id/ask

Request Body:

{
  "question": "How does the authentication system work?",
  "language": "en"
}

Response:

{
  "success": true,
  "answer": "The authentication system uses JWT tokens...",
  "references": [
    {
      "filePath": "src/auth/login.ts",
      "description": "Main authentication logic"
    }
  ]
}

Impact Analysis

Analyze the impact of changes to a file.

POST /v1/projects/:id/analyze

Request Body:

{
  "path": "src/services/user.ts"
}

Response:

{
  "success": true,
  "impact": {
    "directDependencies": [
      "src/utils/crypto.ts",
      "src/db/models/user.ts"
    ],
    "dependents": [
      "src/controllers/auth.ts",
      "src/controllers/profile.ts"
    ],
    "affectedTests": [
      "tests/user.test.ts"
    ],
    "riskLevel": "medium",
    "recommendation": "Changes require testing auth and profile flows"
  }
}

Code Metrics

Get code quality metrics.

GET /v1/projects/:id/metrics

Query Parameters:

Parameter	Type	Description
path	string	Filter by path (optional)

Response:

{
  "success": true,
  "metrics": {
    "summary": {
      "totalFiles": 234,
      "totalLines": 15420,
      "avgComplexity": 4.2,
      "maxComplexity": 18,
      "duplicatePercentage": 3.1
    },
    "byFile": [
      {
        "path": "src/services/complex.ts",
        "lines": 450,
        "complexity": 18,
        "maintainability": 62
      }
    ]
  }
}

Security Scan

Get security vulnerability scan results.

GET /v1/projects/:id/security

Response:

{
  "success": true,
  "scan": {
    "status": "completed",
    "scannedAt": "2024-01-15T10:30:00Z",
    "summary": {
      "high": 2,
      "medium": 5,
      "low": 8
    },
    "issues": [
      {
        "severity": "high",
        "type": "sql-injection",
        "file": "src/db/query.ts",
        "line": 34,
        "description": "Potential SQL injection vulnerability",
        "recommendation": "Use parameterized queries"
      }
    ]
  }
}

Dead Code Detection

Find unused code.

GET /v1/projects/:id/dead-code

Response:

{
  "success": true,
  "deadCode": {
    "unusedExports": [
      {
        "file": "src/utils/helpers.ts",
        "name": "formatDate",
        "line": 45,
        "type": "function"
      }
    ],
    "unusedFiles": [
      "src/legacy/old-service.ts"
    ],
    "estimatedLines": 234
  }
}

Code Duplication

Find duplicated code blocks.

GET /v1/projects/:id/duplication

Response:

{
  "success": true,
  "duplication": {
    "percentage": 3.1,
    "duplicates": [
      {
        "lines": 15,
        "occurrences": [
          { "file": "src/api/users.ts", "start": 45, "end": 60 },
          { "file": "src/api/products.ts", "start": 32, "end": 47 }
        ]
      }
    ]
  }
}

---

Enterprise Analysis

Endpoints for analyzing large projects (50K+ files).

Get Project Estimate

Analyze project size and get tier recommendations.

GET /v1/projects/:id/enterprise/estimate

Response:

{
  "projectId": "proj_abc123",
  "projectName": "large-monorepo",
  "totalFiles": 92135,
  "totalSizeMB": 927.5,
  "recommendation": "quick",
  "estimatedTimeMinutes": 8,
  "languageDistribution": {
    ".rb": 46386,
    ".js": 10075,
    ".vue": 4333,
    ".ts": 1500
  },
  "tiers": {
    "quick": {
      "maxFiles": 1000,
      "estimatedFiles": 1000,
      "skipEmbeddings": true,
      "skipSecurity": true,
      "description": "Fast overview"
    },
    "standard": {
      "maxFiles": 5000,
      "estimatedFiles": 5000,
      "skipEmbeddings": false,
      "skipSecurity": false,
      "description": "Balanced analysis"
    },
    "deep": {
      "maxFiles": 50000,
      "estimatedFiles": 50000,
      "skipEmbeddings": false,
      "skipSecurity": false,
      "description": "Comprehensive analysis"
    }
  }
}

Start Enterprise Indexing

Index a large project with sampling.

POST /v1/projects/:id/enterprise/index

Request Body:

{
  "tier": "standard",
  "sampling": {
    "enabled": true,
    "strategy": "smart",
    "maxFiles": 5000
  },
  "focusDirectories": ["src/core", "src/api"],
  "excludePatterns": ["test", "spec", "__pycache__"]
}

Field	Type	Description
tier	string	quick, standard, or deep
sampling.strategy	string	smart, hot-files, directory-balanced, random
focusDirectories	string[]	Directories to prioritize
excludePatterns	string[]	Patterns to exclude

Response:

{
  "taskId": "task_xyz789",
  "status": "pending",
  "message": "Enterprise indexing task queued"
}

Preview Files to Analyze

Get a preview of which files would be analyzed.

GET /v1/projects/:id/enterprise/files?tier=standard&strategy=smart

Response:

{
  "projectId": "proj_abc123",
  "tier": "standard",
  "strategy": "smart",
  "totalSelected": 5000,
  "maxAllowed": 5000,
  "files": [
    "src/index.ts",
    "src/server/index.ts",
    "package.json"
  ],
  "hasMore": true
}

Check Incremental Changes

Find files changed since a date or commit.

POST /v1/projects/:id/enterprise/incremental

Request Body:

{
  "since": "2024-01-01"
}

Or with a git commit hash:

{
  "since": "abc123f"
}

Response:

{
  "projectId": "proj_abc123",
  "since": "2024-01-01",
  "changedFiles": 234,
  "files": [
    "src/auth/login.ts",
    "src/api/users.ts"
  ],
  "hasMore": true,
  "message": "Found 234 changed files"
}

Get Available Tiers

Get information about analysis tiers.

GET /v1/enterprise/tiers

Response:

{
  "tiers": {
    "quick": {
      "maxFiles": 1000,
      "skipEmbeddings": true,
      "skipSecurity": true,
      "description": "Fast overview"
    },
    "standard": {
      "maxFiles": 5000,
      "skipEmbeddings": false,
      "skipSecurity": false,
      "description": "Balanced analysis"
    },
    "deep": {
      "maxFiles": 50000,
      "skipEmbeddings": false,
      "skipSecurity": false,
      "description": "Comprehensive analysis"
    }
  },
  "samplingStrategies": {
    "smart": "AI-powered selection based on importance",
    "hot-files": "Files with most git commits",
    "directory-balanced": "Equal representation from directories",
    "random": "Random sampling"
  }
}