🚀 Beta: All Pro and Team features are free. Install on GitHub →

Overview Authentication Rate Limits Endpoint Response Try It Live Errors Examples Templates

Overview

The CodeRifts API detects breaking changes between two OpenAPI specifications. Send your old and new specs, get back a full governance report with risk scoring, breaking changes, security findings, and policy violations.

Use it in CI/CD pipelines, local development workflows, or any system that needs to validate API contract changes before deployment.

https://app.coderifts.com/api/v1

Authentication

Include your API key in the Authorization header as a Bearer token:

HTTP Header
Authorization: Bearer cr_live_your_key_here

Don't have a key? Get one free → No credit card required. Free tier includes 50 requests per month.

Rate Limits

TierMonthly RequestsPer MinutePrice
Free5010$0
ProUnlimited60$49/mo

Rate limit information is returned in response headers:

HeaderDescription
X-RateLimit-Remaining-MonthlyRequests remaining this month
X-RateLimit-Limit-MonthlyTotal monthly request limit
X-RateLimit-Remaining-MinuteRequests remaining this minute

Endpoint: POST /v1/diff

Analyze the difference between two OpenAPI specifications and return a full governance report.

Request

cURL
curl -X POST \
  https://app.coderifts.com/api/v1/diff \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "old_spec": "openapi: 3.0.0\ninfo:\n  title: My API\n  version: 1.0.0\npaths:\n  /users:\n    get:\n      summary: List users\n      responses:\n        \"200\":\n          description: OK",
    "new_spec": "openapi: 3.0.0\ninfo:\n  title: My API\n  version: 2.0.0\npaths: {}"
  }'

Request Body

FieldTypeRequiredDescription
old_spec string required The base (old) OpenAPI specification as a YAML or JSON string
new_spec string required The head (new) OpenAPI specification as a YAML or JSON string
config object optional Configuration options (see below)

Config Options

FieldTypeDefaultDescription
format string "json" Response format: "json" or "markdown"
risk_threshold number 50 Risk score threshold (0-100) for should_block
block_on array [] Change types that should trigger blocking (e.g., ["removed-endpoint", "auth-removed"])

Response

200 OK — Success

JSON
{
  "risk_score": 42,
  "risk_level": "moderate",
  "risk_dimensions": {
    "revenue_impact": 6,
    "blast_radius": 4,
    "app_compatibility": 3,
    "security": 0
  },
  "semver_suggestion": "major",
  "breaking_changes": [
    {
      "type": "path.remove",
      "path": "/users",
      "method": "GET",
      "field": "",
      "severity": "high",
      "description": "Endpoint removed"
    }
  ],
  "non_breaking_changes": [],
  "security_findings": [],
  "changelog": {
    "breaking": ["**Removed** endpoint `GET /users`"],
    "added": [],
    "changed": [],
    "deprecated": []
  },
  "policy_violations": [],
  "should_block": false,
  "stats": {
    "total_changes": 1,
    "breaking_count": 1,
    "non_breaking_count": 0,
    "security_count": 0
  }
}

Response Fields

FieldTypeDescription
risk_scorenumberOverall risk score from 0 (safe) to 100 (critical)
risk_levelstringHuman-readable level: minimal, low, moderate, high, critical
risk_dimensionsobjectBreakdown: revenue_impact, blast_radius, app_compatibility, security
semver_suggestionstringSuggested version bump: major, minor, or patch
breaking_changesarrayList of breaking change objects (see below)
non_breaking_changesarrayList of non-breaking change objects
security_findingsarraySecurity-related findings (auth removal, scope changes)
changelogobjectAuto-generated changelog: breaking, added, changed, deprecated
policy_violationsarrayPolicy rule violations based on config
should_blockbooleantrue if risk exceeds threshold or blocked change types found
statsobjectSummary counts: total_changes, breaking_count, non_breaking_count, security_count

Breaking Change Object

FieldTypeDescription
typestringChange type (e.g., path.remove, request.property.removed, response.property.type-changed)
pathstringAPI path affected (e.g., /users/{id})
methodstringHTTP method (GET, POST, etc.)
fieldstringSpecific field name if applicable
severitystringlow, medium, or high
descriptionstringHuman-readable description of the change

Try It Live

Send a real request to the API. This uses the unauthenticated demo endpoint — no API key needed.

Analyzing your specs...

      

Error Codes

The API returns standard HTTP status codes with a JSON error body:

JSON
{
  "error": "missing_spec",
  "message": "Both old_spec and new_spec are required"
}
Error CodeHTTP StatusDescription
missing_spec400Both old_spec and new_spec are required
invalid_spec400One or both specs are not valid OpenAPI (YAML/JSON parse error)
spec_too_large413Request body exceeds 5MB limit
invalid_api_key401Missing, invalid, or expired API key
rate_limited429Monthly or per-minute rate limit exceeded
server_error500Internal server error — contact [email protected]

SDKs & Integration Examples

Copy-paste examples for popular languages and CI/CD platforms.

cURL

Bash
curl -X POST https://app.coderifts.com/api/v1/diff \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $CODERIFTS_API_KEY" \
  -d @- <<EOF
{
  "old_spec": "$(cat old-api.yaml)",
  "new_spec": "$(cat new-api.yaml)"
}
EOF

Python

Python
import requests

with open("old-api.yaml") as f:
    old_spec = f.read()
with open("new-api.yaml") as f:
    new_spec = f.read()

response = requests.post(
    "https://app.coderifts.com/api/v1/diff",
    headers={
        "Content-Type": "application/json",
        "Authorization": f"Bearer {api_key}",
    },
    json={"old_spec": old_spec, "new_spec": new_spec},
)

result = response.json()
print(f"Risk Score: {result['risk_score']}/100")
print(f"Breaking Changes: {len(result['breaking_changes'])}")

if result["should_block"]:
    raise SystemExit("Blocked: breaking changes exceed threshold")

JavaScript (Node.js / fetch)

JavaScript
const fs = require('fs');

const oldSpec = fs.readFileSync('old-api.yaml', 'utf-8');
const newSpec = fs.readFileSync('new-api.yaml', 'utf-8');

const response = await fetch('https://app.coderifts.com/api/v1/diff', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.CODERIFTS_API_KEY}`,
  },
  body: JSON.stringify({ old_spec: oldSpec, new_spec: newSpec }),
});

const result = await response.json();
console.log(`Risk Score: ${result.risk_score}/100`);
console.log(`Breaking Changes: ${result.breaking_changes.length}`);

if (result.should_block) {
  process.exit(1);
}

GitHub Actions

YAML
name: API Contract Check
on: [pull_request]

jobs:
  api-diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check API Breaking Changes
        run: |
          npx @coderifts/cli diff old-api.yaml new-api.yaml \
            --ci --threshold 50
        env:
          CODERIFTS_API_KEY: ${{ secrets.CODERIFTS_API_KEY }}

GitLab CI

YAML
api-contract-check:
  stage: test
  image: node:20
  script:
    - npx @coderifts/cli diff old-api.yaml new-api.yaml --ci --threshold 50
  variables:
    CODERIFTS_API_KEY: $CODERIFTS_API_KEY
  allow_failure: false

Jenkins Pipeline

Groovy
pipeline {
    agent any
    environment {
        CODERIFTS_API_KEY = credentials('coderifts-api-key')
    }
    stages {
        stage('API Contract Check') {
            steps {
                sh 'npx @coderifts/cli diff old-api.yaml new-api.yaml --ci --threshold 50'
            }
        }
    }
}

Configuration Templates

Industry-specific .coderifts.yml templates for your repo. Choose your industry, copy the config, and drop it in your repository root.

YAML
Download

Drop this file as .coderifts.yml in your repository root. CodeRifts will automatically detect and apply it.