REST API Reference

Complete reference for all Code Evolution Lab API endpoints.

Status note. This reference was written against an earlier version of the API and has not been fully re-verified. Endpoint paths and response shapes may have changed. Treat it as a guide rather than a contract, and expect updates.

Base URL

http://localhost:3000

The production base URL is not yet published here.

Authentication

Most endpoints require authentication via JWT Bearer token:

Authorization: Bearer <access_token>

Rate Limiting

Scope	Limit	Window
Global	100 requests	15 minutes
Analysis	10 requests	1 minute

Rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Health Check

GET /health

Check API server status.

Authentication: None required

Response:

{
  "status": "ok",
  "message": "Code Evolution Lab API is running"
}

Authentication Endpoints

POST /api/auth/register

Request:

{
  "email": "[email protected]",
  "password": "securePassword123",
  "name": "John Doe"
}

Response (201):

{
  "message": "Registration successful",
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe"
  }
}

Errors:

400 - Validation error
409 - Email already exists

POST /api/auth/login

Request:

{
  "email": "[email protected]",
  "password": "securePassword123"
}

Response (200):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe",
    "tier": "free"
  }
}

Cookies Set:

refresh_token (HTTP-only, 7 days)

Errors:

401 - Invalid credentials
403 - Account suspended
429 - Too many attempts

GET /api/auth/social/google

Initiate Google OAuth flow.

Response: Redirects to Google OAuth consent screen

GET /api/auth/social/github

Initiate GitHub OAuth flow.

Response: Redirects to GitHub OAuth authorization

POST /api/auth/social/callback

Handle OAuth callback from providers.

Request:

{
  "provider": "google",
  "code": "oauth_authorization_code"
}

Response (200):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "user": {
    "id": "uuid",
    "email": "[email protected]",
    "name": "John Doe",
    "avatarUrl": "https://...",
    "authProvider": "google"
  }
}

POST /api/auth/refresh

Refresh access token using refresh token cookie.

Cookies Required:

refresh_token

Response (200):

{
  "accessToken": "eyJhbGciOiJIUzI1NiIs..."
}

Errors:

401 - Invalid or expired refresh token

POST /api/auth/logout

Logout and invalidate tokens.

Authentication: Required

Response (200):

{
  "message": "Logged out successfully"
}

Actions:

Clears refresh_token cookie
Invalidates session

GET /api/auth/me

Get current authenticated user.

Authentication: Required

Response (200):

{
  "id": "uuid",
  "email": "[email protected]",
  "name": "John Doe",
  "avatarUrl": "https://...",
  "tier": "pro",
  "analysesUsedThisCycle": 45,
  "analysesLimit": 100,
  "createdAt": "2024-01-15T10:30:00Z"
}

Code Analysis Endpoints

POST /api/analyze

Analyze code for performance issues.

Authentication: Required

Request:

{
  "code": "async function getUsers() { ... }",
  "filePath": "example.js",
  "generateSolutions": true
}

Response (200):

{
  "results": [
    {
      "detectorName": "N+1 Query Detector",
      "issues": [
        {
          "id": "issue-uuid",
          "type": "n_plus_1_query",
          "severity": "high",
          "filePath": "example.js",
          "lineNumber": 5,
          "title": "N+1 Query Detected",
          "description": "Database query inside loop...",
          "codeBefore": "for (const order of orders) { await User.findByPk(...) }",
          "estimatedImpact": {
            "severityScore": 75,
            "category": "performance",
            "fixDifficulty": "moderate"
          },
          "solutions": [
            {
              "id": "sol-uuid",
              "rank": 1,
              "type": "batch-query-before-loop",
              "code": "const users = await User.findAll({...})",
              "fitnessScore": 85.2,
              "description": "Batch query before loop",
              "generationMethod": "heuristic",
              "implementationTime": 15,
              "riskLevel": "low"
            }
          ]
        }
      ]
    }
  ],
  "summary": {
    "totalIssues": 1,
    "criticalIssues": 0,
    "highIssues": 1,
    "mediumIssues": 0,
    "score": 75
  }
}

Errors:

400 - Invalid code or missing fields
429 - Analysis rate limit exceeded
403 - Analysis quota exceeded

GET /api/analysis/:analysisId

Get a specific analysis result.

Authentication: Required

Response (200):

{
  "id": "analysis-uuid",
  "repositoryId": "repo-uuid",
  "score": 75,
  "filesAnalyzed": 1,
  "totalIssues": 3,
  "criticalIssues": 0,
  "highIssues": 1,
  "mediumIssues": 2,
  "analyzedAt": "2024-01-15T10:30:00Z",
  "issues": [...]
}

Repository Endpoints

GET /api/repositories

List user’s repositories.

Authentication: Required

Query Parameters:

Parameter	Type	Description
`page`	number	Page number (default: 1)
`limit`	number	Items per page (default: 10)

Response (200):

{
  "repositories": [
    {
      "id": "repo-uuid",
      "name": "my-project",
      "githubUrl": "https://github.com/user/my-project",
      "isPrivate": false,
      "lastAnalyzedAt": "2024-01-15T10:30:00Z",
      "createdAt": "2024-01-10T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 5,
    "pages": 1
  }
}

POST /api/repositories

Add a new repository.

Authentication: Required

Request:

{
  "name": "My Project",
  "githubUrl": "https://github.com/username/repo"
}

Response (201):

{
  "id": "repo-uuid",
  "name": "My Project",
  "githubUrl": "https://github.com/username/repo",
  "isPrivate": false,
  "createdAt": "2024-01-15T10:30:00Z"
}

Errors:

400 - Invalid URL
409 - Repository already exists

GET /api/repositories/:id

Get repository details.

Authentication: Required

Response (200):

{
  "id": "repo-uuid",
  "name": "My Project",
  "githubUrl": "https://github.com/username/repo",
  "isPrivate": false,
  "lastAnalyzedAt": "2024-01-15T10:30:00Z",
  "createdAt": "2024-01-10T08:00:00Z",
  "analyses": [
    {
      "id": "analysis-uuid",
      "score": 75,
      "totalIssues": 3,
      "analyzedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

POST /api/repositories/:id/analyze-github

Analyze a GitHub repository.

Authentication: Required

Response (200):

{
  "message": "Analysis started",
  "analysisId": "analysis-uuid"
}

Subscribe to SSE endpoint for progress updates.

DELETE /api/repositories/:id

Delete a repository.

Authentication: Required

Response (200):

{
  "message": "Repository deleted"
}

User Endpoints

GET /api/user/profile

Get user profile.

Authentication: Required

Response (200):

{
  "id": "uuid",
  "email": "[email protected]",
  "name": "John Doe",
  "avatarUrl": "https://...",
  "phone": null,
  "tier": "pro",
  "createdAt": "2024-01-01T00:00:00Z"
}

PATCH /api/user/profile

Update user profile.

Authentication: Required

Request:

{
  "name": "John Smith",
  "phone": "+1234567890"
}

Response (200):

{
  "message": "Profile updated",
  "user": {
    "id": "uuid",
    "name": "John Smith",
    "phone": "+1234567890"
  }
}

GET /api/user/usage

Get usage statistics.

Authentication: Required

Response (200):

{
  "tier": "pro",
  "analysesUsedThisCycle": 45,
  "analysesLimit": 100,
  "billingCycleDay": 15,
  "lastResetDate": "2024-01-15T00:00:00Z",
  "nextResetDate": "2024-02-15T00:00:00Z"
}

Session Endpoints

GET /api/sessions

List active sessions.

Authentication: Required

Response (200):

{
  "sessions": [
    {
      "id": "session-uuid",
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0...",
      "device": "Desktop",
      "location": "New York, US",
      "lastActive": "2024-01-15T10:30:00Z",
      "isActive": true,
      "isCurrent": true
    }
  ]
}

DELETE /api/sessions/:id

Terminate a session.

Authentication: Required

Response (200):

{
  "message": "Session terminated"
}

DELETE /api/sessions

Terminate all sessions except current.

Authentication: Required

Response (200):

{
  "message": "All other sessions terminated",
  "count": 3
}

Subscription Endpoints

GET /api/subscription/plans

Get available subscription plans.

Authentication: None required

Response (200):

{
  "plans": [
    {
      "id": "free",
      "name": "Free",
      "price": { "monthly": 0, "yearly": 0 },
      "features": [
        "30 analyses per month",
        "All 11 detectors",
        "3 solutions per issue"
      ]
    },
    {
      "id": "pro",
      "name": "Pro",
      "price": { "monthly": 7, "yearly": 60 },
      "features": [
        "100 analyses per month",
        "All 11 detectors",
        "5 solutions per issue",
        "Private repositories"
      ]
    }
  ]
}

See Pricing Tiers for the authoritative limits.

POST /api/subscription/checkout

Create Stripe checkout session.

Authentication: Required

Request:

{
  "planId": "pro",
  "interval": "monthly"
}

Response (200):

{
  "checkoutUrl": "https://checkout.stripe.com/..."
}

POST /api/subscription/portal

Create Stripe customer portal session.

Authentication: Required

Response (200):

{
  "portalUrl": "https://billing.stripe.com/..."
}

POST /api/subscription/webhook

Stripe webhook endpoint.

Authentication: Stripe signature verification

Events Handled:

checkout.session.completed
customer.subscription.updated
customer.subscription.deleted
invoice.payment_succeeded
invoice.payment_failed

Dashboard Endpoints

GET /api/dashboard/stats

Get dashboard statistics.

Authentication: Required

Response (200):

{
  "totalAnalyses": 50,
  "totalIssuesFound": 127,
  "totalIssuesFixed": 85,
  "recentAnalyses": [
    {
      "id": "analysis-uuid",
      "repositoryName": "my-project",
      "score": 75,
      "totalIssues": 3,
      "analyzedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "issuesByType": {
    "n_plus_1_query": 45,
    "memory_leak": 32,
    "inefficient_loop": 28,
    "large_payload": 22
  }
}

Error Responses

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {}
  }
}

Common Error Codes

Code	HTTP Status	Description
`VALIDATION_ERROR`	400	Invalid request data
`UNAUTHORIZED`	401	Missing or invalid token
`FORBIDDEN`	403	Insufficient permissions
`NOT_FOUND`	404	Resource not found
`CONFLICT`	409	Resource already exists
`RATE_LIMITED`	429	Too many requests
`QUOTA_EXCEEDED`	403	Usage limit reached
`INTERNAL_ERROR`	500	Server error