Repo Cat

Quick Start

This guide will help you make your first API call to analyze a GitHub repository.

Prerequisites

  • An API key (required for all scan levels)
  • A tool to make HTTP requests (curl, Postman, etc.)

Making Your First Request

The scan endpoint accepts GET requests with the following query parameters:

ParameterTypeDescription
repostringGitHub repository in format "owner/repo"
levelstringScan level: "basic", "standard", or "deep"
referencestringBranch or tag to scan (optional)
apiKeystringYour API key (required for all scan levels)

Example: Basic Scan

A basic scan requires an API key. It returns repository metadata and heuristics.

cURL

curl -X GET "https://repocat.cloud/api/v1/scan?repo=facebook/react&level=basic" \
  -H "X-API-Key: your-api-key-here"

JavaScript

const response = await fetch(
  'https://repocat.cloud/api/v1/scan?repo=facebook/react&level=basic',
  {
    headers: { 'X-API-Key': 'your-api-key-here' }
  }
);
const data = await response.json();
console.log(data);

Response

{
  "success": true,
  "data": {
    "level": "basic",
    "repo": "facebook/react",
    "scannedAt": "2026-03-29T12:00:00.000Z",
    "metadata": {
      "name": "opencode",
      "description": "The open source coding agent.",
      "stars": 180796,
      "forks": 22271,
      "watchers": 180796,
      "language": "TypeScript",
      "license": "MIT",
      "topics": [],
      "defaultBranch": "dev",
      "size": 296848,
      "openIssues": 7119,
      "contributorsCount": 1,
      "createdAt": "2025-04-30T20:08:00Z",
      "pushedAt": "2026-06-30T13:09:50Z",
      "lastCommitDate": "2026-06-30T11:17:44Z",
      "commitSha": "b329fcceb21e2061bcdb24173fdfbc4d25f73414"
    },
    "heuristics": {
      "commitDensity": {
        "score": 85,
        "commitsPerMonth": 120,
        "description": "Active development with regular commits"
      },
      "packageBloat": {
        "score": 60,
        "dependencyCount": 25,
        "devDependencyRatio": 0.4,
        "description": "Moderate dependency count"
      }
    }
  }
}

Error Handling

The API returns appropriate error codes when something goes wrong.

Status CodeDescription
200Success
400Invalid request parameters
401Invalid or missing API key
403Insufficient permissions or scan limit exceeded
404Repository not found
500Internal server error

Listing Your Scans

Get a list of all your scans with pagination.

cURL

curl -X GET "https://repocat.cloud/api/v1/scans?page=1" \
  -H "X-API-Key: your-api-key-here"

Response

{
  "success": true,
  "scans": [
    {
      "id": 123,
      "repo": "facebook/react",
      "level": "deep",
      "status": "completed",
      "createdAt": "2026-03-29T12:00:00.000Z"
    },
    {
      "id": 122,
      "repo": "vercel/next.js",
      "level": "standard",
      "status": "failed",
      "createdAt": "2026-03-28T10:30:00.000Z"
    }
  ],
  "total": 50,
  "page": 1,
  "totalPages": 5
}

Real-Time Progress with SSE

Track scan progress in real-time using Server-Sent Events.

JavaScript (EventSource)

const eventSource = new EventSource(
  'https://repocat.cloud/api/v1/scans/sse',
  {
    headers: { 'X-API-Key': 'your-api-key-here' }
  }
);

eventSource.addEventListener('scan', (event) => {
  const data = JSON.parse(event.data);
  console.log('Scan update:', data);
});

eventSource.addEventListener('progress', (event) => {
  const data = JSON.parse(event.data);
  console.log('Progress:', data.progress + '%');
});

eventSource.addEventListener('complete', (event) => {
  const data = JSON.parse(event.data);
  console.log('Scan complete:', data.result);
  eventSource.close();
});

eventSource.addEventListener('error', (event) => {
  console.error('Error:', event.data);
});

Event Types

  • scan - Status update (pending, processing, completed, failed)
  • progress - Progress percentage and current stage
  • complete - Final result when scan finishes
  • error - Error message if scan fails

Managing Scans

View, cancel, or delete existing scans.

Get Scan by ID

curl -X GET "https://repocat.cloud/api/v1/scan/123" \
  -H "X-API-Key: your-api-key-here"

Download PDF

curl -X GET "https://repocat.cloud/api/v1/scan/123/pdf" \
  -H "X-API-Key: your-api-key-here" \
  -o scan-result.pdf

Cancel Running Scan

curl -X POST "https://repocat.cloud/api/v1/scan/123/cancel" \
  -H "X-API-Key: your-api-key-here"

Delete Scan

curl -X DELETE "https://repocat.cloud/api/v1/scan/123" \
  -H "X-API-Key: your-api-key-here"

Configuring Webhooks

Set up webhooks to receive HTTP POST requests when scan events occur.

Webhooks Documentation - Full configuration guide

Next Steps

Now that you know how to make API calls, check out the full API reference for more details.