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

All API endpoints require authentication using an API key, including Basic scans.

Base Endpoint

All API requests are made to the following base URL:

https://repocat.cloud

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",
    "models": "poolside/laguna-xs.2:free",       // llm model(s) used
    "metadata": { ... },
    "heuristics": { ... },
    "tldr": { ... },                              // all levels
    "analyzedFiles": [ ... ],                     // standard/deep only
    "staticAnalysis": { ... },                    // standard/deep only
    "codeAnalysis": { ... },                      // deep only
    "vibeAnalysis": { ... }                       // deep only
  }
}

Basic Level Response

{
  "success": true,
  "data": {
    "level": "basic",
    "repo": "owner/repo",
    "scannedAt": "2026-03-29T12:00:00.000Z",
    "models": "string",
    "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",
      "commitSha": "string | null"
    },
    "heuristics": {
      "commitDensity": {
        "score": number,
        "commitsPerMonth": number,
        "description": "string",
        "granularity": "weekly" | "daily",
        "activityHistory": [
          { "startDate": "string", "endDate": "string", "commitCount": number }
        ]
      },
      "packageBloat": {
        "score": number,
        "dependencyCount": number,
        "devDependencyRatio": number,
        "description": "string",
        "keyPackages": string[],
        "monorepoPackages": string[],
        "allDependencyTypes": {
          "peer": string[],
          "bundled": string[],
          "optional": string[]
        },
        "categorizedDependencies": {
          "testing": string[],
          "ui": string[],
          "api": string[],
          "utils": string[],
          "other": string[]
        }
      }
    },
    "tldr": {
      "score": number,
      "summary": "string",
      "keyFindings": string[]
    }
  }
}

Standard Level Response

{
  "success": true,
  "data": {
    "level": "standard",
    "repo": "owner/repo",
    "scannedAt": "2026-03-29T12:00:00.000Z",
    "metadata": { ... },
    "heuristics": { ... },
    "tldr": { ... },
    "analyzedFiles": [
      {
        "path": "string",
        "truncated": boolean,
        "originalSize": number,
        "analysisTypes": string[]
      }
    ],
    "staticAnalysis": {
      "score": number,
      "summary": "string",
      "structure": {
        "score": number,
        "issues": [ { "severity": "string", "text": "string", "category": "string", "file": "string" } ]
      },
      "security": {
        "score": number,
        "issues": [ { "severity": "string", "text": "string", "category": "string", "file": "string" } ]
      },
      "bestPractices": {
        "score": number,
        "issues": [ { "severity": "string", "text": "string", "category": "string", "file": "string" } ]
      }
    }
  }
}

Deep Level Response

{
  "success": true,
  "data": {
    "level": "deep",
    "repo": "owner/repo",
    "scannedAt": "2026-03-29T12:00:00.000Z",
    "metadata": { ... },
    "heuristics": { ... },
    "tldr": { ... },
    "analyzedFiles": [ ... ],
    "staticAnalysis": { ... },
    "codeAnalysis": {
      "score": number,
      "summary": "string",
      "structure": {
        "score": number,
        "issues": [ { "severity": "string", "text": "string", "category": "string", "file": "string" } ]
      },
      "security": {
        "score": number,
        "issues": [ { "severity": "string", "text": "string", "category": "string", "file": "string" } ]
      },
      "bestPractices": {
        "score": number,
        "issues": [ { "severity": "string", "text": "string", "category": "string", "file": "string" } ]
      }
    },
    "vibeAnalysis": {
      "score": number,
      "summary": "string",
      "uniformity": {
        "score": number,
        "issues": [ { "severity": "string", "text": "string", "category": "string", "file": "string" } ]
      },
      "boilerplate": {
        "score": number,
        "issues": [ { "severity": "string", "text": "string", "category": "string", "file": "string" } ]
      },
      "domainFit": {
        "score": number,
        "issues": [ { "severity": "string", "text": "string", "category": "string", "file": "string" } ]
      }
    }
  }
}

Error Response (4xx/5xx)

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

Scan Levels

Basic

Provides fundamental repository information including metadata, heuristics, and TL;DR summary.

• Repository metadata (stars, forks, description, etc.)
• Commit density analysis with activity history
• Package bloat detection with dependency categorization
• TL;DR summary with key findings

Standard

Adds static code analysis across up to 200 files for structure, security, and best practice assessment.

• Everything in Basic
• Static analysis (structure, security, best practices) on up to 200 files
• File-level issue reporting with severity, category, and remediation

Deep

Comprehensive analysis with LLM-powered code review and vibe analysis across up to 30 files.

• Everything in Standard
• LLM-powered code analysis with detailed issue detection
• Vibe analysis (codebase uniformity, boilerplate detection, domain fit)

Get Scan by ID

Retrieve the details of a specific scan by its ID.

Path Parameters

Response

{
  "success": true,
  "scan": {
    "id": 123,
    "user_id": 1,
    "repo": "owner/repo",
    "level": "deep",
    "git_provider": "github",
    "status": "completed",
    "current_step": "finalizing",
    "current_step_num": 5,
    "total_steps": 5,
    "error_message": null,
    "report_id": 456,
    "reference": null,
    "created_at": "2026-03-29T12:00:00.000Z",
    "updated_at": "2026-03-29T12:05:00.000Z",
    "completed_at": "2026-03-29T12:05:00.000Z",
    "result": { ... },
    "subTasks": { ... }
  },
  "prevId": 122,
  "nextId": 124
}

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",
      "currentStep": "consolidating",
      "currentStepNum": 4,
      "totalSteps": 5,
      "reference": null,
      "createdAt": "2026-03-29T12:00:00.000Z",
      "completedAt": "2026-03-29T12:05:00.000Z",
      "durationMs": 300000
    }
  ],
  "total": 50,
  "page": 1,
  "totalPages": 5
}

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": {
    "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,
    "email_notifications_enabled": true,
    "email_on_scan_started": false,
    "email_on_scan_completed": true,
    "email_on_scan_failed": false,
    "email_on_scan_cancelled": false,
    "email_on_subscription_created": true,
    "email_on_subscription_updated": true,
    "email_on_subscription_cancelled": true,
    "email_on_payment_succeeded": true,
    "email_on_payment_failed": true
  }
}

Update Settings

Request Body

Example Request

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

Response

{
  "success": true,
  "settings": {
    "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,
    "email_notifications_enabled": true,
    "email_on_scan_started": false,
    "email_on_scan_completed": true,
    "email_on_scan_failed": false,
    "email_on_scan_cancelled": false,
    "email_on_subscription_created": true,
    "email_on_subscription_updated": true,
    "email_on_subscription_cancelled": true,
    "email_on_payment_succeeded": true,
    "email_on_payment_failed": true
  }
}

Code Examples

JavaScript/TypeScript

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

  const baseUrl = 'https://repocat.cloud';
  const response = await fetch(`${baseUrl}/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('https://repocat.cloud/api/v1/scan', 
                          params=params, 
                          headers=headers)
    return response.json()

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