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 Standard and Deep scans, optional for Basic)
  • A tool to make HTTP requests (curl, Postman, etc.)

Making Your First Request

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

ParameterTypeDescription
repostringGitHub repository in format "owner/repo"
levelstringScan level: "basic", "standard", or "deep"
apiKeystringYour API key (required for standard/deep)

Example: Basic Scan

A basic scan does not require an API key. It returns repository metadata and heuristics.

cURL

curl -X GET "http://repo-cat.futoro.co.uk/api/v1/scan?repo=facebook/react&level=basic" \
  -H "X-API-Key: your-api-key-here"

JavaScript

const response = await fetch(
  'http://repo-cat.futoro.co.uk/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": "react",
      "description": "The library for web and native user interfaces",
      "stars": 215000,
      "forks": 46000,
      "watchers": 215000,
      "language": "JavaScript",
      "license": "MIT",
      "topics": ["react", "javascript", "frontend", "ui"],
      "defaultBranch": "main",
      "size": 15000,
      "openIssues": 1500,
      "contributorsCount": 1500,
      "createdAt": "2013-05-09T22:25:51Z",
      "pushedAt": "2026-03-28T18:30:00Z",
      "lastCommitDate": "2026-03-28T18:30:00Z"
    },
    "heuristics": {
      "commitDensity": {
        "score": 85,
        "commitsPerMonth": 120,
        "description": "Active development with regular commits"
      },
      "packageBloat": {
        "score": 60,
        "dependencyCount": 25,
        "devDependencyRatio": 0.4,
        "description": "Moderate dependency count"
      }
    }
  }
}

Example: Standard/Deep Scan

For standard and deep scans, you need to include your API key in the request header.

cURL

curl -X GET "http://repo-cat.futoro.co.uk/api/v1/scan?repo=facebook/react&level=standard" \
  -H "X-API-Key: your-api-key-here"

JavaScript

const response = await fetch(
  'http://repo-cat.futoro.co.uk/api/v1/scan?repo=facebook/react&level=standard',
  {
    headers: { 'X-API-Key': 'your-api-key-here' }
  }
);
const data = await response.json();
console.log(data);

Response

{
  "success": true,
  "data": {
    "level": "standard",
    "repo": "facebook/react",
    "scannedAt": "2026-03-29T12:00:00.000Z",
    "metadata": { /* ... basic metadata ... */ },
    "codeQuality": {
      "score": 72,
      "testCoverage": 85,
      "lintingIssues": 12
    }
  }
}

Error Handling

The API returns appropriate error codes when something goes wrong.

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

Listing Your Scans

Get a list of all your scans with pagination.

cURL

curl -X GET "http://repo-cat.futoro.co.uk/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"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "totalPages": 3
  }
}

Real-Time Progress with SSE

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

JavaScript (EventSource)

const eventSource = new EventSource(
  'http://repo-cat.futoro.co.uk/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 "http://repo-cat.futoro.co.uk/api/v1/scan/123" \
  -H "X-API-Key: your-api-key-here"

Download PDF

curl -X GET "http://repo-cat.futoro.co.uk/api/v1/scan/123/pdf" \
  -H "X-API-Key: your-api-key-here" \
  -o scan-result.pdf

Cancel Running Scan

curl -X POST "http://repo-cat.futoro.co.uk/api/v1/scan/123/cancel" \
  -H "X-API-Key: your-api-key-here"

Delete Scan

curl -X DELETE "http://repo-cat.futoro.co.uk/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.

PreviousIntroductionNextDashboard