# Backend API — Deprecation and Legacy Compatibility

## Purpose

This document tracks the lifecycle status of all backend API endpoints:
which endpoints are current, which are transitional, and which have been
superseded or are candidates for removal.

---

## Current API Surface

All endpoints require Bearer token authentication (`requireAuth`) unless marked Public.
Admin endpoints additionally require `requireAdmin`.

### Health & Observability (Public)

| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/health` | Current | Basic liveness — returns uptime + loop health |
| GET | `/health/live` | Current | Kubernetes-style liveness probe |
| GET | `/health/ready` | Current | Kubernetes-style readiness probe |
| GET | `/internal/health` | Current | Internal full health dump (not auth-gated; firewall-restrict in prod) |
| GET | `/metrics` | Current | Prometheus metrics via `prom-client` |

### Trading State

| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/state` | Current | Full BotState snapshot for authenticated user |
| GET | `/api/lifecycle/canonical` | Current | Canonical lifecycle event log for a trade |
| GET | `/api/alerts` | Current | Recent alert list |
| GET | `/api/symbol/:symbol` | Current | Per-symbol signal and indicator state |

### Trading Controls (Admin)

| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/internal/trading/status` | Current | Current trading control mode |
| POST | `/internal/trading/pause` | Current | Pause all new trade entries (admin only) |
| POST | `/internal/trading/resume` | Current | Resume trading (admin only) |
| POST | `/api/admin/revert-backfill-batch` | Current | Revert an exit backfill batch (admin only) |

### Config & Feature Flags

| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/config` | Current | Current runtime config subset (public fields only) |
| GET | `/api/feature-flags` | Current | Authoritative feature-flag contract (backtest, tabs) |
| GET | `/api/admin/config/dynamic` | Current | Full dynamic config (admin only) |
| PUT | `/api/admin/config/dynamic` | Current | Update dynamic config entries (admin only) |

### User Profile & Identity

| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/me/profile` | Current | Authenticated user's platform profile |
| PATCH | `/api/me/profile` | Current | Update user profile fields |

### Trading Profiles (Strategies)

| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/profiles` | Current | List trading profiles for authenticated user |
| POST | `/api/profiles` | Current | Create a new trading profile |
| PUT | `/api/profiles/:id` | Current | Replace a trading profile |
| PATCH | `/api/profiles/:id/active` | Current | Toggle profile active/inactive |
| DELETE | `/api/profiles/:id` | Current | Delete a trading profile |

### Orders & Positions

| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/positions/bootstrap` | Current | Initial position state for dashboard bootstrap |
| GET | `/api/trade-history` | Current | Closed trade history for authenticated user |
| GET | `/api/manual-entries` | Current | Manual trade entries for authenticated user |
| POST | `/api/manual-entries` | Current | Create a manual trade entry |
| PUT | `/api/manual-entries/:id` | Current | Update a manual trade entry |
| DELETE | `/api/manual-entries/:id` | Current | Delete a manual trade entry |
| POST | `/api/trade` | Current | Submit a live trade action (entry/exit signal) |
| POST | `/api/close` | Current | Close a position |

### Marketplace

| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/marketplace-presets` | Current | List publicly available strategy presets |
| POST | `/api/marketplace-presets` | Current | Create a marketplace preset (admin only) |

### Backtest

| Method | Path | Status | Notes |
|---|---|---|---|
| POST | `/api/backtest/run` | Current | Run a backtest (gated by `ENABLE_BACKTEST` flag) |

### AI & Diagnostics

| Method | Path | Status | Notes |
|---|---|---|---|
| GET | `/api/ai/health` | Current | AI provider health and fallback chain status |
| POST | `/api/chat` | Current | AI strategy assistant chat endpoint |

### Events & Reconciliation (Admin)

| Method | Path | Status | Notes |
|---|---|---|---|
| DELETE | `/api/events` | Current | Clear operational event log (admin only) |
| GET | `/api/admin/audit` | Current | Trade audit event log — requires `audit-events` Cosmos container (admin only) |
| GET | `/api/reconciliation/backfill/audit` | Current | Backfill audit records (admin only) |
| GET | `/api/reconciliation/backfill/batches` | Current | Backfill batch summary (admin only) |

---

## Transitional / Internal-Only Endpoints

| Path | Notes |
|---|---|
| `/internal/health` | Not auth-gated. Must be firewall-restricted in production. Not for external clients. |
| `/internal/trading/status` | `/internal/` prefix signals operator tooling only. Not part of the public client API contract. |
| `/internal/trading/pause` | Same as above. |
| `/internal/trading/resume` | Same as above. |

---

## Deprecated Endpoints

There are no formally deprecated endpoints in the current monorepo runtime.

Legacy Supabase-backed API variants (direct browser-side table reads) existed in the old
`bytelyst-trading-dashboard-web` repo and were replaced with backend API calls during
Phase 3 migration. Those call paths no longer exist in this codebase.

---

## Planned Additions (Not Yet Implemented)

| Endpoint | Status | Notes |
|---|---|---|
| `GET /api/admin/audit` | Implemented | Queries Cosmos `audit-events` container — activate by creating the container (see docs/BACKEND_AUDIT_SCHEMA.md) |
| `GET /api/push/register` | Planned | Register mobile push token — blocked on push provider selection |
| `DELETE /api/push/register` | Planned | Deregister mobile push token — blocked on push provider selection |

---

## Versioning Policy

- No API version prefix (`/v1/`) is currently in use. All endpoints are implicitly v1.
- Breaking changes require a deprecation notice in this document and a migration period
  of at least one full deploy cycle before removal.
- The `x-request-id` header is the primary correlation key for client/backend tracing.

---

## WebSocket Namespaces

| Namespace | Purpose | Auth |
|---|---|---|
| `/` (root) | Backward-compatible default; all authenticated users | Bearer token required |
| `/trading` | Named user-facing namespace; receives user-scoped BotState | Bearer token required |
| `/admin` | Admin-only namespace; receives full cross-user state | Bearer token + admin role required |

Web and mobile clients connect to `/trading` by default.
The root namespace is retained for backward compatibility.