# API Reference
## AI Operations Center — Complete Endpoint Catalog

**Document Owner:** AiSO Platform Team  
**Last Updated:** May 2026  
**Audience:** Integration Engineer, Frontend Developer, QA

---

## Overview

The application exposes **61 API routes** across **87 method+path combinations**. All routes:
- Accept and return JSON
- Use `Decimal` fields serialized as strings for financial precision
- Return standard HTTP status codes (200, 400, 404, 500)
- Are server-side rendered (no CORS restrictions within the app)

---

## Core Data APIs

| Method | Path | Purpose | Key Params |
|--------|------|---------|------------|
| GET | `/api/deductions` | List all deductions with related data | `?limit=N&skip=N` |
| GET | `/api/deductions-detail/{id}` | Full deduction detail (classification, validity, artifacts) | Path: `id` |
| PATCH | `/api/deductions-detail/resolve` | Record dispute outcome on a deduction | Body: `{deductionId, outcome, resolvedAmount, notes}` |
| GET | `/api/collections` | Ranked collection accounts with scoring | — |
| GET | `/api/invoice-triage` | Invoice list with exceptions and classification | — |
| GET | `/api/invoice-triage/{id}` | Single invoice detail | Path: `id` |
| PATCH | `/api/invoice-triage/{id}` | Update invoice triage status | Body: `{status}` |
| GET | `/api/demand-sensing` | Forecast, actuals, deviation, attribution, inventory risk | — |
| POST | `/api/demand-sensing` | Process planner query via LLM | Body: `{query, skuCode, dc}` |
| GET | `/api/buyer-context` | Supplier and SKU master data for buyer module | — |
| GET | `/api/executive` | Aggregated executive KPIs and financials | — |
| GET | `/api/aged-deductions` | Aged deduction summary for escalation | — |
| POST | `/api/aged-deductions` | Trigger escalation for aged deductions | Body: `{deductionIds, escalationType}` |

---

## Agent Swarm APIs

| Method | Path | Purpose | Key Params |
|--------|------|---------|------------|
| POST | `/api/agent-swarm/run` | Trigger an agent swarm run for any MVP | Body: `{mvp, caseId}` |
| GET | `/api/agent-swarm/list` | List recent agent runs | `?mvp=MVP1&limit=10` |
| GET | `/api/agent-swarm/{runId}` | Full run detail with reasoning trace and proposals | Path: `runId` |
| GET | `/api/agent-status` | Live agent status updates | `?mvp=MVP4&caseId=X` |
| GET | `/api/cross-mvp-signals` | Cross-MVP signal aggregation | `?deductionId=N` or `?invoiceId=N` |

---

## Buyer Copilot APIs

| Method | Path | Purpose | Key Params |
|--------|------|---------|------------|
| POST | `/api/llm-chat` | Streaming LLM chat for buyer copilot | Body: `{message, conversationId, userId}` |
| GET | `/api/buyer-copilot/conversations` | List buyer conversations | `?userId=X` |
| POST | `/api/buyer-copilot/conversations` | Create new conversation | Body: `{userId, title}` |
| GET | `/api/buyer-copilot/conversations/{id}` | Get conversation messages | Path: `id` |
| POST | `/api/buyer-copilot/conversations/{id}` | Send message in conversation | Body: `{message}` |
| POST | `/api/buyer-copilot/action` | Execute a buyer action (PR, acknowledge, etc.) | Body: `{actionKind, payload, conversationId}` |
| POST | `/api/buyer-copilot/pr/{prNumber}/approve` | Approve a purchase requisition | Path: `prNumber` |

---

## Governance & Control APIs

| Method | Path | Purpose | Key Params |
|--------|------|---------|------------|
| GET | `/api/hitl-queue` | List HITL items needing approval | `?mvp=X&status=open&caseId=X` |
| PATCH | `/api/hitl-queue` | Approve/reject HITL item | Body: `{id, status, notes, overrideReason}` |
| GET | `/api/escalations` | List escalation tickets | `?mvp=X` |
| PATCH | `/api/escalations` | Acknowledge or resolve escalation | Body: `{id, status, notes}` |
| POST | `/api/writeback/submit` | Submit writeback request for approval | Body: `{mvp, caseType, caseId, action, payload, amount}` |
| PATCH | `/api/writeback/approve` | Business/IT approval of writeback | Body: `{requestId, tier, approvedBy, notes}` |
| POST | `/api/writeback/execute` | Execute approved writeback via MCP | Body: `{requestId}` |
| GET | `/api/audit-log` | Query immutable audit log | `?mvp=X&limit=N` |
| GET | `/api/notifications` | Aggregated notification center feed | — |

---

## Configuration & Tuning APIs

| Method | Path | Purpose | Key Params |
|--------|------|---------|------------|
| GET | `/api/boundary-conditions` | List boundary conditions | `?mvp=X` |
| PATCH | `/api/boundary-conditions` | Update a boundary condition value | Body: `{mvp, conditionKey, value}` |
| POST | `/api/boundary-conditions` | Reset conditions to defaults | Body: `{action: "reset", mvp}` |
| GET | `/api/scenarios` | List what-if scenarios | `?mvp=X` |
| POST | `/api/scenarios` | Run a what-if scenario | Body: `{mvp, name, overrides}` |
| PATCH | `/api/scenarios` | Apply scenario as new defaults | Body: `{scenarioId}` |

---

## Evaluation & Learning APIs

| Method | Path | Purpose | Key Params |
|--------|------|---------|------------|
| GET | `/api/agreement-metrics` | Agreement-with-human metrics + disagreement drill-down | `?mvp=X` |
| POST | `/api/agreement-metrics` | Reseed/recompute agreement metrics | — |
| GET | `/api/agreement-rate` | Raw agreement rate data | `?mvp=X` |
| POST | `/api/agreement-rate` | Record a new agreement/disagreement | Body: `{mvp, classValue, agreed}` |
| GET | `/api/golden-cases` | List unlabeled golden cases (MVP1) | — |
| POST | `/api/golden-cases` | Save SME label on golden case | Body: `{id, classification, verdict, ...}` |
| GET | `/api/override-reasons` | List override reasons and patterns | `?mvp=X` |
| POST | `/api/override-reasons` | Record new override reason | Body: `{caseType, agentProposal, smeCorrection, reason, ...}` |
| GET | `/api/prompt-versions` | List prompt versions | `?mvp=X&status=active` |
| POST | `/api/prompt-versions` | Create new prompt version | Body: `{mvp, promptType, systemPrompt}` |
| PATCH | `/api/prompt-versions` | Activate/deactivate prompt version | Body: `{id, status}` |
| GET | `/api/prompt-refinements` | List suggested refinements | `?status=pending` |
| POST | `/api/prompt-refinements` | Create refinement suggestion | Body: `{sourcePromptVersionId, patterns, suggestion}` |
| PATCH | `/api/prompt-refinements` | Review/implement refinement | Body: `{id, status, reviewedBy}` |

---

## Per-MVP Evaluation APIs

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/mvp2/agreement` | MVP2 collections agreement metrics |
| GET | `/api/mvp2/score` | MVP2 scoring model outputs |
| GET/POST | `/api/mvp2/golden-cases` | MVP2 collections golden cases |
| GET | `/api/mvp3/agreement` | MVP3 invoice triage agreement metrics |
| GET | `/api/mvp3/validity` | MVP3 invoice validity engine results |
| GET/POST | `/api/mvp3/golden-cases` | MVP3 invoice golden cases |
| GET | `/api/mvp4/agreement` | MVP4 buyer copilot agreement metrics |
| GET/POST | `/api/mvp4/policy-evaluate` | MVP4 policy engine evaluation |
| GET/POST | `/api/mvp4/golden-cases` | MVP4 buyer golden cases |

---

## Metrics & Value APIs

| Method | Path | Purpose | Key Params |
|--------|------|---------|------------|
| GET | `/api/mvp-metrics` | KPI baselines and current values per MVP | `?mvp=X` |
| GET | `/api/value-ledger` | Value ledger entries and aggregations | `?mvp=X&caseId=X` |
| POST | `/api/value-ledger` | Create value ledger entry | Body: `{mvp, caseType, caseId, category, bucket, amountUsd}` |
| GET | `/api/cross-mvp-trust` | Platform-wide trust score and breakdown | — |
| GET | `/api/proposals` | Action proposals across all MVPs | `?mvp=X&status=proposed` |

---

## Validation & Orchestration APIs

| Method | Path | Purpose | Key Params |
|--------|------|---------|------------|
| POST | `/api/deduction-validate` | Run 7-point validity engine on deduction | Body: `{deductionId}` |
| GET | `/api/mvp1-orchestrate/{deductionId}` | Run full MVP1 orchestration pipeline | Path: `deductionId` |
| POST | `/api/invoice-triage/run-batch` | Batch-run invoice triage | Body: `{invoiceIds}` |
| POST | `/api/invoice-triage/seed` | Seed invoice triage test data | — |
| GET | `/api/invoice-triage/arbitrage` | List arbitrage opportunities | — |
| GET | `/api/invoice-validate` | List recent invoice validity checks | — |
| POST | `/api/invoice-validate` | Run validity engine on invoice | Body: `{invoiceId}` |
| POST | `/api/shortage-reconciliation` | Run GR/ASN/BOL three-way match | Body: `{invoiceId}` |

---

## Infrastructure APIs

| Method | Path | Purpose |
|--------|------|---------|
| GET | `/api/mcp-health` | MCP gateway health (circuit breaker status per system) |
| GET | `/api/search` | Global search across 6 entity types |
| GET | `/api/test-runner` | Run E2E and database integrity tests |
| POST | `/api/seed-data` | Seed core reference data |
| POST | `/api/seed-extra` | Seed additional scenario data |
