---
name: diagnose-api-mismatch
description: Compare frontend fetch URLs and auth configurations against backend route definitions to identify endpoint path mismatches and missing credentials causing 404 or 401 errors. Use when debugging API call failures, auth issues between frontend and backend, or when reviewing full-stack code for integration bugs.
---

# Diagnose API Mismatch

Systematic workflow to find and fix frontend/backend API integration bugs.

## When to Use

- Frontend fetch returns 404 or 401
- SSO/cookie auth works in browser but fails in code
- Suspected URL path mismatch between frontend call and backend route
- Reviewing full-stack changes for integration correctness

## Steps

1. **Locate the frontend fetch call**
   - Use `grep` to find `fetch(`, `axios`, or `$.ajax` in the frontend codebase
   - Extract the full URL/path being requested

2. **Locate the backend route definition**
   - Search backend route files (Express, FastAPI, Flask, etc.) for the corresponding endpoint
   - Note the exact path, HTTP method, and auth middleware

3. **Compare paths**
   - Check for missing/extra path segments (e.g., `/api` prefix, `/fetch` suffix)
   - Verify HTTP method matches (`GET` vs `POST`)

4. **Compare auth configuration**
   - Check if backend expects Bearer token, cookie session, or both
   - Check if frontend `fetch` includes:
     - `credentials: 'include'` (required for SSO cookies)
     - `Authorization: Bearer <token>` header (required for token auth)
   - If using dual auth (cookie + Bearer), ensure both are sent when available

5. **Identify the fix**
   - Path mismatch → update frontend URL or backend route
   - Missing credentials → add `credentials: 'include'`
   - Missing header → conditionally attach `Authorization` when token exists
   - Wrong method → align frontend and backend

## Output Format

Report findings as:

```
Issue: <404|401|METHOD_MISMATCH|etc.>
Frontend: <file> calls <method> <url>
Backend:  <file> defines <method> <route> with <auth>
Root cause: <explanation>
Fix: <specific code change>
```

## Example

**Problem:** `CrawlEdit.jsx` article crawl fails with HTTP 401.

**Diagnosis:**
- Frontend (`CrawlEdit.jsx`): `fetch('/api/crawl')` — no `credentials` option, no `Authorization` header
- Backend (`routes/crawl.js`): `router.post('/api/crawl', requireAuth)` — accepts Bearer token or SSO cookie

**Root cause:** Raw `fetch` omits SSO cookies by default, and no Bearer token is attached.

**Fix:**
```javascript
const token = localStorage.getItem('token');
fetch('/api/crawl', {
  method: 'POST',
  credentials: 'include',
  headers: {
    ...(token && { 'Authorization': `Bearer ${token}` }),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(data),
});
```

## Tools

- `grep` — find fetch calls and route definitions
- `read_file` — inspect specific frontend/backend files
- `edit_file` / `write_file` — apply fixes