When APIs change, know what breaks.
Continuous third-party API contract inspection, deterministic schema diffing, application code impact analysis, and Gemini-powered failure autopsies with verified unified diff patches.
Built for the Devpost Build With AI: Basics learning hackathon (October 2026).
Modern applications depend on dozens of external third-party APIs (payment processors, authentication providers, shipping trackers, communication gateways).
When an external provider changes its response payload—renaming a field, removing a legacy identifier, or changing an object structure:
- The API doesn't return an HTTP 500. It returns an HTTP 200 with an altered payload.
- Traditional monitors report "Healthy". Uptime checks and latency probes stay green.
- Your application fails silently. Downstream code reads
undefined, passes corrupt state to services, and breaks user workflows. - Debugging is painful. Developers must reverse-engineer the provider's unannounced contract drift and hunt through their repository to find every affected call site.
API Autopsy connects external API contract drift directly to the lines of code in your codebase that depend on them:
API changed → customer_id removed → payment.customer_id → undefined → Customer lookup fails → Recommended fix
- Discover Integrations: Read-only repository scanner detects outbound HTTP requests, endpoint paths, and field access references with transparent confidence levels.
- Capture Baselines: Establishes a known-good structural baseline for each configured API endpoint.
- Continuous Monitoring & Dual-Path Pipeline:
- Real Checks: Periodic background scheduler polls external APIs and validates live response structures against captured baselines.
- Simulations: Controlled sandbox executes breaking payload mutations (e.g., canonical
customer_id→customer.iddemo) to test application resilience safely.
- Deterministic Diff Engine: Compares JSON schemas recursively—ignoring harmless property ordering while flagging breaking deletions, renames, and type mutations.
- Repository Impact Scan: Queries repository files for direct references to altered fields (dot notation, bracket syntax, destructuring) using pattern-based matching.
- Gemini Root Cause Autopsy: Google Gemini reasons over the deterministic diff and verified code evidence to reconstruct the failure propagation path and generate a unified diff patch (
--- a/file +++ b/file). - Strict Provenance Attribution: Clear boundaries ensure pre-loaded demo fixtures are never misrepresented as live repository scans.
┌───────────────────────────────────────────────────────────┐
│ Next.js Dashboard UI │
│ (Monitor Detail, Live Pipeline, Autopsy Report, Registry)│
└───────────────▲───────────────────────────▲───────────────┘
│ HTTP REST │ Socket.IO Events
┌───────────────▼───────────────────────────▼───────────────┐
│ server.ts (Custom Server) │
│ - Next.js Request Router │
│ - Socket.IO Real-Time Dispatcher │
│ - In-Process Polling Scheduler (5 min interval) │
└───────────────────────────────┬───────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────┐
│ Dual-Path Incident Pipeline │
│ │
│ Real HTTP Check Path Simulation Path │
│ (executeMonitorCheck) (executeSimulation) │
│ │ │ │
│ └────────────────┬───────────────┘ │
│ │ │
│ ▼ │
│ 1. Recursive JSON Schema Diff │
│ │ │
│ ▼ │
│ 2. Severity Classification (Breaking/Additive)│
│ │ │
│ ▼ │
│ 3. Repository Impact Analysis │
│ (Live Repo Scan vs Canonical Demo Fixture) │
│ │ │
│ ▼ │
│ 4. Gemini Autopsy Reasoning │
│ (Root Cause + Failure Path + Unified Patch)│
└───────────────────────────────┬───────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────┐
│ PostgreSQL Database │
│ (Users, Repositories, Monitors, Baselines, Incidents, │
│ Autopsy Reports, Encrypted Credentials) │
└───────────────────────────────────────────────────────────┘
- Node.js:
v20.9.0or higher - Package Manager:
npm - PostgreSQL:
v15or higher (local or managed instance, e.g. Neon, Supabase) - Google Gemini API Key: with access to
gemini-3.8-flash(or compatible model) - GitHub Account: with permissions to register a GitHub OAuth App and GitHub App
Copy .env.example to .env.local and configure your credentials:
cp .env.example .env.local| Variable | Required In | Description | Format / Example |
|---|---|---|---|
DATABASE_URL |
Production & Dev | PostgreSQL pooled connection string | postgresql://user:pass@ep-xyz.neon.tech/autopsy?sslmode=require |
NEXTAUTH_SECRET |
Production & Dev | 32-byte session encryption secret | openssl rand -base64 32 |
NEXTAUTH_URL |
Production & Dev | Canonical URL of the application | https://your-project.vercel.app (or http://localhost:3000) |
GITHUB_OAUTH_CLIENT_ID |
Production & Dev | GitHub OAuth App Client ID (user authentication) | Ov23li... |
GITHUB_OAUTH_CLIENT_SECRET |
Production & Dev | GitHub OAuth App Client Secret | 6b2d18... |
GITHUB_APP_ID |
Production & Dev | GitHub App ID (repository code scanning) | 123456 |
GITHUB_APP_PRIVATE_KEY |
Production & Dev | GitHub App RSA Private Key (PEM format with \n) |
"-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----" |
GITHUB_APP_CLIENT_ID |
Production & Dev | GitHub App Client ID | Iv23... |
GITHUB_APP_CLIENT_SECRET |
Production & Dev | GitHub App Client Secret | a1b2c3... |
GEMINI_API_KEY |
Production & Dev | Google GenAI API Key for Autopsy reasoning | AIzaSy... |
GEMINI_MODEL |
Production & Dev | Gemini model identifier | gemini-3.8-flash |
ENCRYPTION_KEY |
Production & Dev | 32-byte AES-256 key as 64 hex characters | openssl rand -hex 32 |
CRON_SECRET |
Production & Dev | Bearer secret for /api/cron/monitor-tick |
openssl rand -hex 32 |
PORT |
Local Dev Only | Custom server HTTP port (Do NOT set on Vercel) | 3000 |
Security Note:
.env,.env.local, and real secrets are strictly excluded in.gitignore. Real credentials must never be committed to Git.
npm installApply migrations using Drizzle ORM:
npm run db:pushAPI Autopsy uses a custom Node.js server (server.ts) that hosts Next.js, Socket.IO, and the background polling scheduler in a unified process:
npm run devVisit http://localhost:3000 to open the application.
API Autopsy is designed for seamless native Next.js deployment on Vercel without relying on custom server infrastructure.
- Fork or push the repository to GitHub:
https://github.com/7ds-adarsh/Autopsy - In the Vercel Dashboard, select Add New... → Project.
- Import your GitHub repository.
- Framework Preset: Next.js (automatically detected).
- Build Command:
next build(default). - Output Directory:
.next(default). - Configure all Required Environment Variables (see checklist below) under Environment Variables.
- Click Deploy.
- Recommended Providers: Neon, Supabase, or any managed PostgreSQL instance with a connection pooler (e.g. PgBouncer).
- Serverless Pooling: Use the pooled connection string (port 6543 on Supabase, or
-poolerendpoint on Neon). API Autopsy's DB client is configured withmax: 5, a 10-second idle timeout, and 5-second connection timeout to keep serverless function cold starts low. - Applying Schema to Production:
Run migrations locally targeting your production database URL (never run migrations as an automatic build side effect):# Option A: Run migrations via Drizzle Kit DATABASE_URL="postgresql://user:pass@ep-pooler.neon.tech/autopsy?sslmode=require" npm run db:migrate # Option B: Push schema directly DATABASE_URL="postgresql://user:pass@ep-pooler.neon.tech/autopsy?sslmode=require" npm run db:push
In GitHub Settings → Developer Settings → OAuth Apps:
- Application name: API Autopsy (Production)
- Homepage URL:
https://your-project.vercel.app - Authorization callback URL:
https://your-project.vercel.app/api/auth/callback/github - Copy Client ID and generate a Client Secret to set as
GITHUB_OAUTH_CLIENT_IDandGITHUB_OAUTH_CLIENT_SECRET.
In GitHub Settings → Developer Settings → GitHub Apps:
- GitHub App name: API Autopsy Scanner (Production)
- Homepage URL:
https://your-project.vercel.app - Callback URL:
https://your-project.vercel.app/api/github/app/callback - Setup URL:
https://your-project.vercel.app/api/github/app/callback(Redirect on update checked) - Permissions: Repository permissions → Contents (Read-only), Metadata (Read-only).
- Private Key: Click Generate a private key. In Vercel environment variables, paste the private key either with literal
\nor as a multiline string. - Set
GITHUB_APP_ID,GITHUB_APP_PRIVATE_KEY,GITHUB_APP_CLIENT_ID, andGITHUB_APP_CLIENT_SECRET.
- Hobby Plan Limitation: Vercel Cron on the Hobby plan is restricted to once per day (
0 0 * * *). Setting a 5-minute interval invercel.jsonwill cause Vercel build/deployment failures on Hobby accounts. - External Cron Invocation (Recommended for 5-min checks):
Use an external scheduler (e.g. cron-job.org, GitHub Actions scheduled workflow, or Upstash QStash) to invoke the protected endpoint every 5 minutes:The endpoint is idempotent: it only checks enabled monitors whosePOST https://your-project.vercel.app/api/cron/monitor-tick Authorization: Bearer <CRON_SECRET>
lastCheckedAt + intervalMinuteshas elapsed. - If Unattended Cron is Not Configured: Automatic background polling remains inactive, but manual "Check Now" and "Simulate API Change" remain fully operational on-demand.
- Testing the Canonical Demo: Open any configured API monitor, click Simulate API Change, choose the pre-loaded Canonical Breaking Change, and click Run Simulation. Progress events are written to PostgreSQL and polled at
/api/incidents/[id]/progress, rendering the live forensic investigation pipeline and unified diff patch without requiring Socket.IO. - Testing Manual Checks: Click Check Now on any monitor with an established baseline to verify live endpoint responses.
Run unit and integration test suites:
# Run Vitest test suite
npm test
# Run TypeScript compilation check
npx tsc --noEmitThe test suite covers:
lib/diff/schema-diff.test.ts: Recursive JSON structural diffing (additions, deletions, type alterations, nested renames, order invariance).lib/monitor/canonical-demo.test.ts: Simulation configuration resolution, explicit gating of canonical demo evidence, and non-canonical safety.lib/monitor/slice5-ui-integration.test.ts: End-to-end simulation payload resolution, incident creation contracts, and provenance tagging.lib/pipeline/demo-cleanup.test.ts: Demo data cleanup safety invariants, target identification, and production guard testing.
Before recording demo videos or presenting at the hackathon, you can safely reset development and demo data to a clean slate.
- Preserved: User accounts, GitHub OAuth identities, linked repositories, canonical demo monitor (
Acme Payments API,POST /payments), known-good baseline, and encrypted credentials. - Removed: Non-canonical test monitors, test baselines, test incidents, autopsy reports, and pipeline events.
- Guardrails: Refuses to run against production databases (
NODE_ENV=productionor production hosts) unless--allow-productionis explicitly passed. Never truncates tables or deletes users. Operates in an atomic PostgreSQL transaction with automatic rollback on error.
Inspect exactly which records will be preserved and which will be deleted without modifying the database:
npm run demo:cleanup:previewRequires both --execute and --confirm flags:
npm run demo:cleanup -- --execute --confirmEnsure the canonical monitor is healthy with 0 incidents:
npm run demo:cleanup -- --verifyRun the canonical simulation end-to-end to verify that the canonical monitor, baseline, and pipeline generate a live incident, autopsy report, and pipeline events:
npm run demo:verify-simulationAPI Autopsy supports two execution paths that converge on the exact same core pipeline:
| Dimension | Real API Check (executeMonitorCheck) |
Simulation (executeSimulation) |
|---|---|---|
| Trigger | "Check Now" button or 5-min scheduled background tick | "Simulate API Change" dialog |
| Payload Source | Live HTTP request to configured external endpoint | Injected fixture JSON or user-pasted test payload |
| Credentials | Decrypted server-side for outbound call only | Not accessed or needed |
isSimulation |
false |
true (tagged on all records, badges, and alerts) |
| External Impact | Real external request made | Zero external network calls |
| Code Impact | Pattern-based code reference scan of connected repo | Pattern-based scan, or explicitly gated canonical demo fixture |
- Canonical Demo Gating: Pre-loaded code evidence (
src/services/payment.ts:19) is injected only when the user explicitly triggers the designated canonical demo (useCanonicalDemo: true). - No Fabricated Impact: For custom responses or monitors without a linked repository,
applicationImpactis never fabricated. Gemini assigns appropriately low confidence. - Explicit UI Provenance: The Autopsy Report explicitly differentiates sources:
Canonical demo fixture — not retrieved from your repositoryVerified repository scan evidenceNo direct code references found
- Pattern-Based Code Reference Scanner: The repository scanner uses regex and pattern matching for outbound HTTP calls (
fetch,axios,got) and field accesses. Highly dynamic metaprogramming or complex reflection may not be detected with high confidence. - Single-Process Polling Scheduler: The background monitor scheduler runs as an in-process singleton (
setInterval) suitable for local development and single-instance deployments. For horizontal multi-pod clusters, an external distributed queue (such as BullMQ, Redis, or Cloud Tasks) should be used. - Read-Only Patch Delivery: API Autopsy generates standard unified diff patches (
.patch) for developer review and copying; it does not automatically commit changes to user repositories.
MIT © 2026 API Autopsy Contributors.