API Reference

Introduction

The Repo Cat REST API allows you to programmatically analyze GitHub repositories, manage scans, and retrieve results. This is the traditional REST API — for AI tool integration, see the MCP Server documentation.

The API uses standard HTTP methods (GET, POST, DELETE) and returns JSON responses.

Authentication

Most API endpoints require authentication using an API key. Basic scans can be performed without an API key, but Standard and Deep scans require authentication.

Base Endpoint

All API requests are made to the following base URL:

http://repo-cat.futoro.co.uk

Scan Endpoint

Analyze a GitHub repository and get metadata and heuristics.

Query Parameters

Headers

Response Format

Success Response (200)

{
  "success": true,
  "data": {
    "level": "basic" | "standard" | "deep",
    "repo": "owner/repo",
    "scannedAt": "2026-03-29T12:00:00.000Z",
    "metadata": { ... },
    "heuristics": { ... },
    "codeQuality": { ... },       // standard/deep only
    "security": { ... },          // standard/deep only
    "contributorStats": { ... },  // standard/deep only
    "aiAnalysis": { ... }         // deep only
  }
}

Basic Level Response

{
  "success": true,
  "data": {
    "level": "basic",
    "repo": "owner/repo",
    "scannedAt": "2026-03-29T12:00:00.000Z",
    "metadata": {
      "name": "string",
      "description": "string | null",
      "stars": number,
      "forks": number,
      "watchers": number,
      "language": "string | null",
      "license": "string | null",
      "topics": string[],
      "defaultBranch": "string",
      "size": number,
      "openIssues": number,
      "contributorsCount": number,
      "createdAt": "string",
      "pushedAt": "string | null",
      "lastCommitDate": "string | null"
    },
    "heuristics": {
      "commitDensity": {
        "score": number,
        "commitsPerMonth": number,
        "description": "string"
      },
      "packageBloat": {
        "score": number,
        "dependencyCount": number,
        "devDependencyRatio": number,
        "description": "string"
      }
    }
  }
}

Standard Level Response

{
  "success": true,
  "data": {
    "level": "standard",
    "repo": "owner/repo",
    "scannedAt": "2026-03-29T12:00:00.000Z",
    "metadata": { ... },
    "heuristics": { ... },
    "codeQuality": {
      "score": number,
      "testCoverage": number,
      "lintingIssues": number,
      "testFilesRatio": number
    },
    "security": {
      "score": number,
      "vulnerabilities": number,
      "outdatedDependencies": string[],
      "securityAdvisories": string[]
    },
    "contributorStats": {
      "activeContributors": number,
      "avgResponseTime": number,
      "prMergeRate": number,
      "topContributors": string[]
    }
  }
}

Deep Level Response

{
  "success": true,
  "data": {
    "level": "deep",
    "repo": "owner/repo",
    "scannedAt": "2026-03-29T12:00:00.000Z",
    "metadata": { ... },
    "heuristics": { ... },
    "codeQuality": { ... },
    "security": { ... },
    "contributorStats": { ... },
    "aiAnalysis": {
      "score": number,
      "architectureScore": number,
      "maintainabilityScore": number,
      "recommendations": [
        {
          "type": "performance" | "security" | "maintainability",
          "priority": "high" | "medium" | "low",
          "title": "string",
          "description": "string",
          "file": "string",
          "line": number
        }
      ],
      "summary": "string"
    }
  }
}

Error Response (4xx/5xx)

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Scan Levels

Basic

Provides fundamental repository information including metadata and basic heuristics. Does not require an API key.

• Repository metadata (stars, forks, description, etc.)
• Commit density analysis
• Package bloat detection

Standard

Enhanced analysis with static code quality assessment. Requires an API key.

• Everything in Basic
• Static code analysis
• Security issue detection
• Best practices recommendations

Deep

Comprehensive analysis with detailed recommendations. Requires an API key.

• Everything in Standard
• AI-powered code analysis
• Architecture recommendations
• Performance optimization suggestions

Get Scan by ID

Retrieve the details of a specific scan by its ID.

Path Parameters

Response

{
  "success": true,
  "scan": {
    "id": 123,
    "repo": "owner/repo",
    "level": "deep",
    "status": "completed",
    "result": { ... },
    "createdAt": "2026-03-29T12:00:00.000Z"
  }
}

Download Scan PDF

Download a scan result as a PDF document.

Path Parameters

Response

Returns PDF binary with Content-Type: application/pdf headers.

Cancel Scan

Cancel a running scan. Only works on scans with status "processing".

Path Parameters

Response

{ "success": true }

Delete Scan

Delete a scan and its associated results.

Path Parameters

Response

{ "success": true }

List Scans

Get a paginated list of your scans.

Query Parameters

Response

{
  "success": true,
  "scans": [
    {
      "id": 123,
      "repo": "owner/repo",
      "level": "deep",
      "status": "completed",
      "createdAt": "2026-03-29T12:00:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "totalPages": 3
  }
}

Scan Progress (SSE)

Connect to real-time scan progress updates using Server-Sent Events.

Response

Returns an event stream with the following event types:

• scan - Scan status change
• progress - Scan progress update
• complete - Scan completed
• error - Scan error

Example Event

event: scan
data: {"id":123,"status":"processing","progress":50,"stage":"analyzing-code"}

event: complete
data: {"id":123,"status":"completed","result":{...}}

User Settings

Get and update user settings including notifications and webhooks.

Get Settings

Response

{
  "success": true,
  "settings": {
    "defaultLevel": "standard",
    "notifications": true,
    "email": "user@example.com",
    "webhook_url": "https://your-app.com/webhook",
    "webhook_enabled": true,
    "webhook_on_scan_started": false,
    "webhook_on_scan_completed": true,
    "webhook_on_scan_failed": false,
    "webhook_on_scan_cancelled": false
  }
}

Update Settings

Request Body

Example Request

{
  "defaultLevel": "deep",
  "webhook_url": "https://your-app.com/webhook",
  "webhook_enabled": true,
  "webhook_on_scan_completed": true,
  "webhook_on_scan_failed": true
}

Response

{
  "success": true,
  "settings": {
    "defaultLevel": "deep",
    "notifications": true,
    "email": "user@example.com",
    "webhook_url": "https://your-app.com/webhook",
    "webhook_enabled": true,
    "webhook_on_scan_started": false,
    "webhook_on_scan_completed": true,
    "webhook_on_scan_failed": true,
    "webhook_on_scan_cancelled": false
  }
}

Code Examples

JavaScript/TypeScript

async function scanRepo(repo, level, apiKey) {
  const params = new URLSearchParams({
    repo,
    level,
    ...(apiKey && { apiKey }),
  });

  const response = await fetch(`/api/v1/scan?${params}`);
  return response.json();
}

// Usage
const result = await scanRepo(facebook/react, 'basic');
console.log(result.data.metadata.stars);

Python

import requests

def scan_repo(repo, level, api_key=None):
    params = {
        'repo': repo,
        'level': level,
    }
    headers = {}
    if api_key:
        headers['X-API-Key'] = api_key
    
    response = requests.get('http://repo-cat.futoro.co.uk/api/v1/scan', 
                          params=params, 
                          headers=headers)
    return response.json()

# Usage
result = scan_repo(facebook/react, 'basic')
print(result['data']['metadata']['stars'])