# Backend: API Design

---
**Phase:** Phase 0 (Planning)  
**Status:** Draft — finalize in Phase 1  
**Owner:** Backend Architect  
**References:**
- `/docs/backend/architecture.md`
- `/docs/backend/payment-flow.md`
- `/docs/backend/security.md`
---

## 1. Principles
- REST with versioning (`/api/v1`), consistent envelope and errors.
- Tenant-scoped resources; role-based authorization.
- Idempotent ingestion/webhook endpoints; trace IDs for debugging.

> Resource set is archetype‑specific. Endpoints below are a **pipeline/classification example** — adapt for chat‑first, generation, or automation products.

## 2. Core Resources (high-level)
- `/auth` — login, tenant context, token refresh.
- `/tenants` — tenant profile, roles, invites.
- `/integrations` — connect sources (OAuth2/webhooks), view health, rotate secrets, webhook endpoints.
- `/records` — list/filter, detail (raw + normalized + reasoning), bulk actions, reprocess.
- `/rules` — CRUD, enable/disable, test/preview, stats.
- `/processing` — trigger re-evaluation (rules → embeddings → LLM), inspect outcomes.
- `/approvals` — approval queue, approve/override, optional rule creation.
- `/reports` — dashboards/summary generation, export status/download.
- `/billing` — session/portal links, subscription status (webhook-driven).
- `/events` — read-only event log feed for downstream agents.
- `/files/attachments` — uploads/metadata (if exposed).

## 3. Payments/Billing (Provider-agnostic)
- `POST /billing/session` — create checkout session for subscription/plan change.
- `GET /billing/status` — current subscription status (webhook-driven source of truth).
- `GET /billing/portal` — customer portal link for payment method/plan management.
- `POST /billing/webhooks/provider` — verify signature; idempotent subscription updates; log billing events.

## 4. Ingestion/Webhooks
- Receivers for external providers (e.g., `/integrations/webhooks/{provider}`): verify signature, dedupe, enqueue to BullMQ; emit `INGESTED` with `source_agent`.

## 5. Processing & Approvals
- `POST /processing/run` — trigger re-evaluation for a scoped set (source/date/status).
- `POST /approvals/{id}/approve` — accept decision; log `APPROVED`.
- `POST /approvals/{id}/override` — override outcome; optional rule payload; log `APPROVED` and `RULE_CREATED` when applicable.

## 6. Events
- `GET /events` — read-only feed (paginated) for downstream agents/clients; filters: tenant, type, time range, source_agent.

## 7. Response Envelope (example)
```json
{
  "data": { ... },
  "error": null,
  "meta": { "traceId": "..." }
}
```
Errors: `data = null`, `error` with code/message/context.