# AI Intelligence Gateway — Swagger / OpenAPI

## Live interactive docs (recommended)

With the gateway running (`uvicorn app.main:app --reload --host 0.0.0.0 --port 8000`):

| Doc | Localhost route |
|-----|-----------------|
| **Swagger UI** | http://localhost:8000/docs |
| ReDoc | http://localhost:8000/redoc |
| OpenAPI JSON | http://localhost:8000/openapi.json |

Authorize with header: `X-Internal-Token: <INTERNAL_API_TOKEN from .env>`  
(`GET /api/v1/health` and `GET /api/v1/ready` need no auth.)

---

## Static OpenAPI files (this folder)

| File | Scope |
|------|--------|
| [`ALL_APIS.openapi.yaml`](./ALL_APIS.openapi.yaml) | **Every API** (62 operations) — full request/response schemas |
| [`ALL_APIS.openapi.json`](./ALL_APIS.openapi.json) | Same schema as JSON |
| [`M1_EMPLOYER_SIDE.openapi.yaml`](./M1_EMPLOYER_SIDE.openapi.yaml) | Milestone M1 employer-side subset (+ Platform placeholders) |

### How to open the static YAML

1. **Swagger Editor** — https://editor.swagger.io → File → Import file  
2. **VS Code / Cursor** — OpenAPI / Swagger preview extension on the YAML  
3. **Live gateway** — http://localhost:8000/docs (always matches running code)

Regenerate the full export after route/schema changes:

```bash
source venv/bin/activate
python3 -c "
from pathlib import Path
import json, yaml
from app.main import app
schema = app.openapi()
schema['servers'] = [
  {'url': 'http://localhost:8000', 'description': 'Local AI Gateway'},
]
Path('docs/swagger/ALL_APIS.openapi.json').write_text(json.dumps(schema, indent=2)+'\n')
Path('docs/swagger/ALL_APIS.openapi.yaml').write_text(yaml.dump(schema, sort_keys=False, allow_unicode=True))
print('updated')
"
```

---

## All APIs (62)

Base path: `/api/v1` · Auth: `X-Internal-Token`

### Health
| Method | Path |
|--------|------|
| GET | `/health` |
| GET | `/ready` |

### Personas & scorecards
| Method | Path |
|--------|------|
| GET | `/personas` |
| POST | `/personas/custom` |
| POST | `/scorecards/generate` |

### Content generation & screening
| Method | Path |
|--------|------|
| POST | `/questions/generate` |
| POST | `/questions/from-role` |
| POST | `/job-descriptions/draft` |
| POST | `/job-descriptions/rewrite` |
| POST | `/documents/parse` |
| POST | `/resume-match/score` |
| POST | `/prep-plans/generate` |
| POST | `/job-matching/recommend` |
| POST | `/assessments/generate` |
| POST | `/assessments/grade` |
| POST | `/aptitude/generate` |
| POST | `/aptitude/grade` |
| POST | `/coding/judge` |
| POST | `/case-studies/generate` |
| POST | `/case-studies/grade` |
| POST | `/scenarios/generate` |
| POST | `/scenarios/grade` |
| POST | `/puzzles/generate` |
| POST | `/puzzles/grade` |
| POST | `/interview-preview/generate` |
| POST | `/interview-preview/regenerate-question` |
| POST | `/interview-preview/define-follow-up-logic` |
| POST | `/interview-preview/merge-custom-questions` |
| POST | `/interview-preview/validate-lock` |
| POST | `/interview-tracks/generate` |
| POST | `/badges/recommend` |
| POST | `/talent-scouting/rank` |
| POST | `/candidate-profiles/summarize` |
| POST | `/translate` |

### Live interview loop
| Method | Path |
|--------|------|
| POST | `/interviews/next-question` |
| POST | `/interviews/evaluate-answer` |
| POST | `/interviews/follow-up` |
| POST | `/interviews/summarize` |
| POST | `/transcription` |
| POST | `/tts/synthesize` |
| POST | `/video-intelligence` |
| POST | `/behavioral-analysis` |
| POST | `/confidence-scoring/evaluate` |
| POST | `/answers/evaluate` |
| POST | `/candidate-scoring` |
| POST | `/skill-gap/analyze` |
| POST | `/hiring-fit/predict` |
| POST | `/bias-detection/analyze` |
| POST | `/interview-highlights/generate` |
| POST | `/reports/panelist-notes` |
| POST | `/reports/evaluation-pdf` |
| POST | `/reference-checks/questionnaire` |
| POST | `/reference-checks/report` |
| POST | `/progress-analytics/analyze` |
| POST | `/cultural-sensitivity/adapt` |
| POST | `/face-verification/verify` |
| POST | `/id-verification/verify` |
| POST | `/proctoring/analyze` |
| POST | `/dei-analytics/analyze` |

### Enterprise AI
| Method | Path |
|--------|------|
| POST | `/manager-clone` |
| POST | `/market-research/questions` |
| POST | `/voice-cloning` |

---

## M1 Employer Side (subset)

See [`M1_EMPLOYER_SIDE.openapi.yaml`](./M1_EMPLOYER_SIDE.openapi.yaml) for the milestone-focused doc (personas, JD, questions, interview preview, scorecards, plus Platform NestJS placeholders).