New Feature

API Archeology

Dig into your API's past. Analyze the full git history of any OpenAPI spec, score stability over time, identify the endpoints that break most often, and get actionable recommendations — all from a single API call.

Install on GitHub View API Reference

POST /api/v1/archeology/analyze

// Response
{
  "repo": "acme-corp/payments-api",
  "spec_path": "api/openapi.yaml",
  "summary": {
    "total_commits_analyzed": 47,
    "total_breaking_changes": 12,
    "breaking_change_rate": 0.26,
    "stability_score": 74,
    "stability_grade": "C",
    "stability_trend": "improving"
  },
  "hotspots": [
    { "path": "/v2/payments", "breaking_count": 5, "stability": "volatile" },
    { "path": "/v2/refunds", "breaking_count": 3, "stability": "unstable" }
  ],
  "top_patterns": [
    { "pattern": "removed_endpoint", "count": 7 },
    { "pattern": "field_removed", "count": 4 }
  ],
  "recommendation": "High breaking change rate on /v2/payments. Consider versioning this endpoint or adding a deprecation policy."
}

What API Archeology does

One endpoint. Complete historical context.

📜

Git History Scan

Fetches every commit that touched your spec file over a configurable lookback window (default: 90 days) and diffs consecutive versions.

📊

Stability Scoring

Computes a 0–100 stability score and an A–F grade based on your breaking change rate. Tracks whether your API is improving or degrading over time.

🔥

Hotspot Detection

Identifies the specific endpoints that have been broken most frequently, ranked by breaking change count and classified as stable, unstable, or volatile.

🧩

Pattern Recognition

Aggregates breaking change types across all commits — endpoint removals, field removals, type changes — so you can see which patterns recur most.

📈

Trend Analysis

Compares the first and second halves of the analysis window to determine whether your API stability is improving, degrading, or stable.

💡

Actionable Recommendations

Every report ends with a plain-English recommendation tailored to your stability grade and hotspot patterns, so you know exactly what to fix first.

Stability Grades

Every report includes a letter grade so you can benchmark at a glance.

Excellent

Score ≥ 90
≤ 10% breaking rate

Good

Score 75–89
11–25% breaking rate

Fair

Score 50–74
26–50% breaking rate

Poor

Score 25–49
51–75% breaking rate

Critical

Score < 25
> 75% breaking rate

API Reference

Two endpoints. No configuration required.

POST /api/v1/archeology/analyze

Fetches the commit history from GitHub and returns a full archeology report. Reports are also cached in the database for retrieval via the GET endpoint.

Request Body

{
  "repo": "owner/repo",          // required — GitHub repo in owner/repo format
  "spec_path": "api/openapi.yaml", // required — path to the OpenAPI spec file
  "lookback_days": 90            // optional — default 90, max 365
}

Optional Headers

X-GitHub-Token: ghp_your_token_here  // Recommended for private repos or high-volume use

GET /api/v1/archeology/report

Returns the most recent cached report for a given repo and spec path. Useful for dashboards and CI integrations that want to read results without re-running the analysis.

Query Parameters

GET /api/v1/archeology/report?repo=owner/repo&spec_path=api/openapi.yaml

Quick Start

Get your first archeology report in under a minute.

Install CodeRifts on GitHub

Install the GitHub App to your organization or repository. No configuration file needed for the Archeology API.

Install on GitHub →

Run your first analysis

Call the analyze endpoint with your repo and spec path. Replace YOUR_API_KEY with your CodeRifts API key.

curl -X POST https://app.coderifts.com/api/v1/archeology/analyze \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "repo": "your-org/your-repo",
    "spec_path": "api/openapi.yaml",
    "lookback_days": 90
  }'

Retrieve cached reports

Once analyzed, fetch the cached report at any time without re-running the full GitHub scan.

curl "https://app.coderifts.com/api/v1/archeology/report?repo=your-org/your-repo&spec_path=api/openapi.yaml" \
  -H "Authorization: Bearer YOUR_API_KEY"

Built for every team

API Archeology fits naturally into your existing workflows.

Platform Engineering

Add stability grades to your internal developer portal. Surface the APIs with the worst track records before teams build new integrations against them.

API Governance

Use the stability score as an objective metric in your API review process. Require a minimum grade before promoting an API to production.

Incident Post-Mortems

After a breaking change causes an outage, use the timeline to understand the pattern and the recommendation to prevent recurrence.

CI/CD Integration

Run archeology analysis as part of your release pipeline. Fail the build if the stability grade drops below your threshold.