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.
Authentication
Include your API key in the Authorization header as a Bearer token:
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
| Tier | Monthly Requests | Per Minute | Price |
|---|---|---|---|
| Free | 50 | 10 | $0 |
| Pro | Unlimited | 60 | $49/mo |
Rate limit information is returned in response headers:
| Header | Description |
|---|---|
X-RateLimit-Remaining-Monthly | Requests remaining this month |
X-RateLimit-Limit-Monthly | Total monthly request limit |
X-RateLimit-Remaining-Minute | Requests remaining this minute |
Endpoint: POST /v1/diff
Analyze the difference between two OpenAPI specifications and return a full governance report.
Request
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
| Field | Type | Required | Description |
|---|---|---|---|
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
| Field | Type | Default | Description |
|---|---|---|---|
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
{
"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
| Field | Type | Description |
|---|---|---|
risk_score | number | Overall risk score from 0 (safe) to 100 (critical) |
risk_level | string | Human-readable level: minimal, low, moderate, high, critical |
risk_dimensions | object | Breakdown: revenue_impact, blast_radius, app_compatibility, security |
semver_suggestion | string | Suggested version bump: major, minor, or patch |
breaking_changes | array | List of breaking change objects (see below) |
non_breaking_changes | array | List of non-breaking change objects |
security_findings | array | Security-related findings (auth removal, scope changes) |
changelog | object | Auto-generated changelog: breaking, added, changed, deprecated |
policy_violations | array | Policy rule violations based on config |
should_block | boolean | true if risk exceeds threshold or blocked change types found |
stats | object | Summary counts: total_changes, breaking_count, non_breaking_count, security_count |
Breaking Change Object
| Field | Type | Description |
|---|---|---|
type | string | Change type (e.g., path.remove, request.property.removed, response.property.type-changed) |
path | string | API path affected (e.g., /users/{id}) |
method | string | HTTP method (GET, POST, etc.) |
field | string | Specific field name if applicable |
severity | string | low, medium, or high |
description | string | Human-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.
Error Codes
The API returns standard HTTP status codes with a JSON error body:
{
"error": "missing_spec",
"message": "Both old_spec and new_spec are required"
}
| Error Code | HTTP Status | Description |
|---|---|---|
missing_spec | 400 | Both old_spec and new_spec are required |
invalid_spec | 400 | One or both specs are not valid OpenAPI (YAML/JSON parse error) |
spec_too_large | 413 | Request body exceeds 5MB limit |
invalid_api_key | 401 | Missing, invalid, or expired API key |
rate_limited | 429 | Monthly or per-minute rate limit exceeded |
server_error | 500 | Internal server error — contact [email protected] |
SDKs & Integration Examples
Copy-paste examples for popular languages and CI/CD platforms.
cURL
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
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)
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
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
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
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.
Drop this file as .coderifts.yml in your repository root. CodeRifts will automatically detect and apply it.